valtech-components 2.0.687 → 2.0.689

package/src/lib/services/content/content-types/documentation.ts

@@ -0,0 +1,369 @@
+/**
+ * Documentation Content Type
+ *
+ * Represents technical documentation with navigation,
+ * sections, and structured content blocks.
+ */
+
+import { ArticleMetadata } from '../../../components/organisms/article/types';
+import { ContentDocument, ContentMeta, ContentBlock, ContentConfig } from '../types';
+import { ContentTransformer } from '../transformer';
+
+/**
+ * Navigation link for prev/next page navigation
+ */
+export interface DocNavLink {
+  /** Page title */
+  title: string;
+  /** Page slug/URL */
+  slug: string;
+}
+
+/**
+ * Documentation document interface
+ */
+export interface Documentation extends ContentDocument<'docs'> {
+  /** Documentation page title */
+  title: string;
+  /** Section name (e.g., "Getting Started", "API Reference") */
+  section?: string;
+  /** Version of the documentation */
+  version?: string;
+  /** Previous page navigation */
+  prevPage?: DocNavLink;
+  /** Next page navigation */
+  nextPage?: DocNavLink;
+  /** Table of contents items (auto-generated from headings if not provided) */
+  toc?: { text: string; level: number; id: string }[];
+}
+
+/**
+ * Generates a URL-friendly ID from text
+ */
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .trim();
+}
+
+/**
+ * Extracts table of contents from content blocks
+ */
+function extractToc(content: ContentBlock[]): { text: string; level: number; id: string }[] {
+  const toc: { text: string; level: number; id: string }[] = [];
+
+  for (const block of content) {
+    if (block.type === 'heading') {
+      toc.push({
+        text: block.text,
+        level: block.level,
+        id: slugify(block.text),
+      });
+    }
+  }
+
+  return toc;
+}
+
+/**
+ * DocsBuilder provides a fluent API for creating documentation pages.
+ *
+ * @example
+ * ```typescript
+ * const docs = new DocsBuilder()
+ *   .title('Installation Guide')
+ *   .section('Getting Started')
+ *   .version('1.0.0')
+ *   .heading('Prerequisites', 1)
+ *   .paragraph('Before you begin, ensure you have...')
+ *   .callout('Node.js 18+ is required', 'warning')
+ *   .heading('Installation', 1)
+ *   .code('npm install valtech-components', 'bash')
+ *   .prevPage('Introduction', '/docs/intro')
+ *   .nextPage('Configuration', '/docs/config')
+ *   .build();
+ *
+ * // Convert to ArticleMetadata
+ * const article = docs.toArticle();
+ * ```
+ */
+export class DocsBuilder {
+  private doc: Partial<Documentation> = {
+    type: 'docs',
+    content: [],
+    meta: {},
+    config: { showMeta: false, showTableOfContents: true },
+  };
+
+  /**
+   * Sets the documentation page title
+   */
+  title(title: string): this {
+    this.doc.title = title;
+    return this;
+  }
+
+  /**
+   * Sets the section name
+   */
+  section(section: string): this {
+    this.doc.section = section;
+    return this;
+  }
+
+  /**
+   * Sets the documentation version
+   */
+  version(version: string): this {
+    this.doc.version = version;
+    return this;
+  }
+
+  /**
+   * Sets the previous page navigation
+   */
+  prevPage(title: string, slug: string): this {
+    this.doc.prevPage = { title, slug };
+    return this;
+  }
+
+  /**
+   * Sets the next page navigation
+   */
+  nextPage(title: string, slug: string): this {
+    this.doc.nextPage = { title, slug };
+    return this;
+  }
+
+  /**
+   * Sets the slug for the page
+   */
+  slug(slug: string): this {
+    this.doc.meta = {
+      ...this.doc.meta,
+      slug,
+    };
+    return this;
+  }
+
+  /**
+   * Sets the ID for the page
+   */
+  id(id: string): this {
+    this.doc.meta = {
+      ...this.doc.meta,
+      id,
+    };
+    return this;
+  }
+
+  /**
+   * Sets tags for the documentation page
+   */
+  tags(...tags: string[]): this {
+    this.doc.meta = {
+      ...this.doc.meta,
+      tags,
+    };
+    return this;
+  }
+
+  /**
+   * Sets the category
+   */
+  category(category: string): this {
+    this.doc.meta = {
+      ...this.doc.meta,
+      category,
+    };
+    return this;
+  }
+
+  // Content block methods
+
+  /**
+   * Adds a heading block
+   */
+  heading(text: string, level: 1 | 2 | 3 = 2): this {
+    this.doc.content!.push({ type: 'heading', level, text });
+    return this;
+  }
+
+  /**
+   * Adds a paragraph block
+   */
+  paragraph(text: string, emphasis?: boolean): this {
+    this.doc.content!.push({ type: 'paragraph', text, emphasis });
+    return this;
+  }
+
+  /**
+   * Adds a code block
+   */
+  code(code: string, language?: string): this {
+    this.doc.content!.push({ type: 'code', code, language });
+    return this;
+  }
+
+  /**
+   * Adds a command/terminal block
+   */
+  command(command: string): this {
+    this.doc.content!.push({ type: 'command', command });
+    return this;
+  }
+
+  /**
+   * Adds a callout/note block
+   */
+  callout(text: string, variant: 'info' | 'warning' | 'success' | 'error' = 'info', title?: string): this {
+    this.doc.content!.push({ type: 'callout', text, variant, title });
+    return this;
+  }
+
+  /**
+   * Adds an info callout (alias for callout with info variant)
+   */
+  info(text: string, title?: string): this {
+    return this.callout(text, 'info', title);
+  }
+
+  /**
+   * Adds a warning callout
+   */
+  warning(text: string, title?: string): this {
+    return this.callout(text, 'warning', title);
+  }
+
+  /**
+   * Adds an error callout
+   */
+  error(text: string, title?: string): this {
+    return this.callout(text, 'error', title);
+  }
+
+  /**
+   * Adds a success callout
+   */
+  success(text: string, title?: string): this {
+    return this.callout(text, 'success', title);
+  }
+
+  /**
+   * Adds an unordered list
+   */
+  list(items: string[]): this {
+    this.doc.content!.push({ type: 'list', items });
+    return this;
+  }
+
+  /**
+   * Adds an ordered/numbered list
+   */
+  orderedList(items: string[]): this {
+    this.doc.content!.push({ type: 'list', items, ordered: true });
+    return this;
+  }
+
+  /**
+   * Adds a checklist
+   */
+  checklist(items: string[]): this {
+    this.doc.content!.push({ type: 'list', items, checklist: true });
+    return this;
+  }
+
+  /**
+   * Adds an image block
+   */
+  image(src: string, alt: string, caption?: string): this {
+    this.doc.content!.push({ type: 'image', src, alt, caption });
+    return this;
+  }
+
+  /**
+   * Adds a quote block
+   */
+  quote(text: string, author?: string, source?: string): this {
+    this.doc.content!.push({ type: 'quote', text, author, source });
+    return this;
+  }
+
+  /**
+   * Adds a divider
+   */
+  divider(style?: 'line' | 'dots' | 'space'): this {
+    this.doc.content!.push({ type: 'divider', style });
+    return this;
+  }
+
+  /**
+   * Adds a button/CTA
+   */
+  button(text: string, href?: string, color?: 'primary' | 'secondary' | 'success'): this {
+    this.doc.content!.push({ type: 'button', text, href, color });
+    return this;
+  }
+
+  /**
+   * Configures rendering options
+   */
+  config(config: Partial<ContentConfig>): this {
+    this.doc.config = { ...this.doc.config, ...config };
+    return this;
+  }
+
+  /**
+   * Builds the final Documentation object
+   */
+  build(): Documentation {
+    const content = this.doc.content || [];
+
+    // Auto-generate TOC if not provided and showTableOfContents is enabled
+    if (!this.doc.toc && this.doc.config?.showTableOfContents) {
+      this.doc.toc = extractToc(content);
+    }
+
+    return {
+      type: 'docs',
+      title: this.doc.title || 'Untitled Documentation',
+      section: this.doc.section,
+      version: this.doc.version,
+      prevPage: this.doc.prevPage,
+      nextPage: this.doc.nextPage,
+      toc: this.doc.toc,
+      meta: this.doc.meta as ContentMeta,
+      content,
+      config: this.doc.config,
+    };
+  }
+
+  /**
+   * Builds and converts to ArticleMetadata
+   */
+  toArticle(): ArticleMetadata {
+    return ContentTransformer.toArticle(this.build());
+  }
+
+  /**
+   * Resets the builder for reuse
+   */
+  clear(): this {
+    this.doc = {
+      type: 'docs',
+      content: [],
+      meta: {},
+      config: { showMeta: false, showTableOfContents: true },
+    };
+    return this;
+  }
+}
+
+/**
+ * Creates a new DocsBuilder instance
+ */
+export function docs(): DocsBuilder {
+  return new DocsBuilder();
+}

package/src/lib/services/content/content-types/news.ts

@@ -0,0 +1,328 @@
+/**
+ * News Article Content Type
+ *
+ * Represents a news article or announcement with headline,
+ * summary, featured image, and structured content blocks.
+ */
+
+import { ArticleMetadata } from '../../../components/organisms/article/types';
+import { ContentDocument, ContentMeta, ContentBlock, ContentConfig } from '../types';
+import { ContentTransformer } from '../transformer';
+
+/**
+ * News article document interface
+ */
+export interface NewsArticle extends ContentDocument<'news'> {
+  /** News headline */
+  headline: string;
+  /** Short summary for listings */
+  summary: string;
+  /** Featured image URL */
+  featuredImage?: string;
+  /** Breaking news flag */
+  breaking?: boolean;
+  /** News source/outlet */
+  source?: string;
+  /** Related articles */
+  relatedArticles?: { title: string; slug: string }[];
+}
+
+/**
+ * Calculates estimated reading time based on word count
+ * @param content - Array of content blocks
+ * @returns Estimated minutes to read
+ */
+function calculateReadingTime(content: ContentBlock[]): number {
+  const wordsPerMinute = 200;
+  let wordCount = 0;
+
+  for (const block of content) {
+    if ('text' in block && typeof block.text === 'string') {
+      wordCount += block.text.split(/\s+/).length;
+    }
+    if (block.type === 'list') {
+      wordCount += block.items.join(' ').split(/\s+/).length;
+    }
+  }
+
+  return Math.max(1, Math.ceil(wordCount / wordsPerMinute));
+}
+
+/**
+ * NewsBuilder provides a fluent API for creating news articles.
+ *
+ * @example
+ * ```typescript
+ * const news = new NewsBuilder()
+ *   .headline('New Product Launch Announced')
+ *   .summary('Company reveals groundbreaking new product...')
+ *   .author('Jane Smith', '/avatars/jane.jpg', 'Technology Reporter')
+ *   .publishedAt(new Date())
+ *   .breaking()
+ *   .featuredImage('/images/product-launch.jpg')
+ *   .paragraph('In a surprise announcement today...')
+ *   .quote('This is our most innovative product yet', 'CEO John Doe')
+ *   .build();
+ *
+ * // Convert to ArticleMetadata
+ * const article = news.toArticle();
+ * ```
+ */
+export class NewsBuilder {
+  private article: Partial<NewsArticle> = {
+    type: 'news',
+    content: [],
+    meta: {},
+    config: { showMeta: true },
+  };
+
+  /**
+   * Sets the news headline
+   */
+  headline(headline: string): this {
+    this.article.headline = headline;
+    return this;
+  }
+
+  /**
+   * Sets the news summary
+   */
+  summary(summary: string): this {
+    this.article.summary = summary;
+    return this;
+  }
+
+  /**
+   * Sets the featured image URL
+   */
+  featuredImage(url: string): this {
+    this.article.featuredImage = url;
+    return this;
+  }
+
+  /**
+   * Marks the article as breaking news
+   */
+  breaking(value: boolean = true): this {
+    this.article.breaking = value;
+    return this;
+  }
+
+  /**
+   * Sets the news source/outlet
+   */
+  source(source: string): this {
+    this.article.source = source;
+    return this;
+  }
+
+  /**
+   * Sets the article author
+   */
+  author(name: string, avatar?: string, role?: string): this {
+    this.article.meta = {
+      ...this.article.meta,
+      author: { name, avatar, role },
+    };
+    return this;
+  }
+
+  /**
+   * Sets the publication date
+   */
+  publishedAt(date: Date | string): this {
+    this.article.meta = {
+      ...this.article.meta,
+      publishedAt: date,
+    };
+    return this;
+  }
+
+  /**
+   * Sets tags for the article
+   */
+  tags(...tags: string[]): this {
+    this.article.meta = {
+      ...this.article.meta,
+      tags,
+    };
+    return this;
+  }
+
+  /**
+   * Sets the category
+   */
+  category(category: string): this {
+    this.article.meta = {
+      ...this.article.meta,
+      category,
+    };
+    return this;
+  }
+
+  /**
+   * Sets the slug
+   */
+  slug(slug: string): this {
+    this.article.meta = {
+      ...this.article.meta,
+      slug,
+    };
+    return this;
+  }
+
+  /**
+   * Sets the ID
+   */
+  id(id: string): this {
+    this.article.meta = {
+      ...this.article.meta,
+      id,
+    };
+    return this;
+  }
+
+  /**
+   * Adds related articles
+   */
+  relatedArticles(articles: { title: string; slug: string }[]): this {
+    this.article.relatedArticles = articles;
+    return this;
+  }
+
+  // Content block methods
+
+  /**
+   * Adds a heading block
+   */
+  heading(text: string, level: 1 | 2 | 3 = 2): this {
+    this.article.content!.push({ type: 'heading', level, text });
+    return this;
+  }
+
+  /**
+   * Adds a paragraph block
+   */
+  paragraph(text: string, emphasis?: boolean): this {
+    this.article.content!.push({ type: 'paragraph', text, emphasis });
+    return this;
+  }
+
+  /**
+   * Adds a quote block
+   */
+  quote(text: string, author?: string, source?: string): this {
+    this.article.content!.push({ type: 'quote', text, author, source });
+    return this;
+  }
+
+  /**
+   * Adds an image block
+   */
+  image(src: string, alt: string, caption?: string): this {
+    this.article.content!.push({ type: 'image', src, alt, caption });
+    return this;
+  }
+
+  /**
+   * Adds an unordered list
+   */
+  list(items: string[]): this {
+    this.article.content!.push({ type: 'list', items });
+    return this;
+  }
+
+  /**
+   * Adds an ordered/numbered list
+   */
+  orderedList(items: string[]): this {
+    this.article.content!.push({ type: 'list', items, ordered: true });
+    return this;
+  }
+
+  /**
+   * Adds a callout/note block
+   */
+  callout(text: string, variant: 'info' | 'warning' | 'success' | 'error' = 'info', title?: string): this {
+    this.article.content!.push({ type: 'callout', text, variant, title });
+    return this;
+  }
+
+  /**
+   * Adds a divider
+   */
+  divider(style?: 'line' | 'dots' | 'space'): this {
+    this.article.content!.push({ type: 'divider', style });
+    return this;
+  }
+
+  /**
+   * Adds a button/CTA
+   */
+  button(text: string, href?: string, color?: 'primary' | 'secondary' | 'success'): this {
+    this.article.content!.push({ type: 'button', text, href, color });
+    return this;
+  }
+
+  /**
+   * Configures rendering options
+   */
+  config(config: Partial<ContentConfig>): this {
+    this.article.config = { ...this.article.config, ...config };
+    return this;
+  }
+
+  /**
+   * Builds the final NewsArticle object
+   */
+  build(): NewsArticle {
+    const content = this.article.content || [];
+
+    return {
+      type: 'news',
+      headline: this.article.headline || 'Untitled News',
+      summary: this.article.summary || '',
+      featuredImage: this.article.featuredImage,
+      breaking: this.article.breaking,
+      source: this.article.source,
+      relatedArticles: this.article.relatedArticles,
+      meta: this.article.meta as ContentMeta,
+      content,
+      config: this.article.config,
+    };
+  }
+
+  /**
+   * Builds and converts to ArticleMetadata
+   */
+  toArticle(): ArticleMetadata {
+    return ContentTransformer.toArticle(this.build());
+  }
+
+  /**
+   * Gets the estimated reading time in minutes
+   */
+  getReadingTime(): number {
+    return calculateReadingTime(this.article.content || []);
+  }
+
+  /**
+   * Resets the builder for reuse
+   */
+  clear(): this {
+    this.article = {
+      type: 'news',
+      content: [],
+      meta: {},
+      config: { showMeta: true },
+    };
+    return this;
+  }
+}
+
+/**
+ * Creates a new NewsBuilder instance
+ */
+export function news(): NewsBuilder {
+  return new NewsBuilder();
+}