cms-renderer 0.0.0

package/lib/image/lazy-load.ts

@@ -0,0 +1,209 @@
+/**
+ * Lazy Loading Utilities
+ *
+ * Reusable IntersectionObserver-based lazy loading with
+ * connection-aware quality adjustment.
+ *
+ * This module provides:
+ * - useLazyLoad: Hook for deferred loading when elements enter viewport
+ * - getConnectionAwareQuality: Adjusts image quality based on network speed
+ */
+
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface LazyLoadOptions {
+  /** Root margin for early loading (default: "200px") */
+  rootMargin?: string;
+  /** Threshold for intersection (default: 0) */
+  threshold?: number;
+  /** Callback when element enters viewport */
+  onEnter?: () => void;
+}
+
+export interface LazyLoadResult {
+  /** Callback ref to attach to the element */
+  ref: (node: HTMLElement | null) => void;
+  /** Whether the element has entered the viewport */
+  inView: boolean;
+}
+
+// =============================================================================
+// useLazyLoad Hook
+// =============================================================================
+
+/**
+ * IntersectionObserver-based lazy loading hook.
+ *
+ * Triggers when an element approaches the viewport. Once triggered,
+ * the observer disconnects (one-shot behavior).
+ *
+ * @param options - Configuration options
+ * @returns Object with ref callback and inView state
+ *
+ * @example
+ * ```tsx
+ * function LazyComponent() {
+ *   const { ref, inView } = useLazyLoad({ rootMargin: '200px' });
+ *
+ *   return (
+ *     <div ref={ref}>
+ *       {inView && <ExpensiveContent />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useLazyLoad(options: LazyLoadOptions = {}): LazyLoadResult {
+  const { rootMargin = '200px', threshold = 0, onEnter } = options;
+  const [inView, setInView] = useState(false);
+  const observerRef = useRef<IntersectionObserver | null>(null);
+
+  const ref = useCallback(
+    (node: HTMLElement | null) => {
+      // Disconnect previous observer
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+        observerRef.current = null;
+      }
+
+      // No node to observe
+      if (!node) return;
+
+      // Create new observer
+      observerRef.current = new IntersectionObserver(
+        ([entry]) => {
+          if (entry?.isIntersecting) {
+            setInView(true);
+            onEnter?.();
+            // Disconnect after first intersection (one-shot)
+            observerRef.current?.disconnect();
+            observerRef.current = null;
+          }
+        },
+        { rootMargin, threshold }
+      );
+
+      observerRef.current.observe(node);
+    },
+    [rootMargin, threshold, onEnter]
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (observerRef.current) {
+        observerRef.current.disconnect();
+        observerRef.current = null;
+      }
+    };
+  }, []);
+
+  return { ref, inView };
+}
+
+// =============================================================================
+// Connection-Aware Quality
+// =============================================================================
+
+/**
+ * Network Information API types (not in standard TypeScript lib).
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API
+ */
+interface NetworkInformation {
+  effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
+  downlink?: number;
+  saveData?: boolean;
+}
+
+interface NavigatorWithConnection extends Navigator {
+  connection?: NetworkInformation;
+}
+
+/**
+ * Quality presets based on connection type.
+ */
+const QUALITY_PRESETS = {
+  'slow-2g': 30,
+  '2g': 50,
+  '3g': 65,
+  '4g': 80,
+  saveData: 40,
+  default: 80,
+} as const;
+
+/**
+ * Returns appropriate image quality based on network conditions.
+ *
+ * Uses the Network Information API when available to detect:
+ * - Data saver mode (returns lowest quality)
+ * - Effective connection type (slow-2g, 2g, 3g, 4g)
+ *
+ * Falls back to default quality (80) when:
+ * - Running on server (SSR)
+ * - Network Information API not supported
+ *
+ * @returns Quality value between 30-80
+ *
+ * @example
+ * ```typescript
+ * const quality = getConnectionAwareQuality();
+ * const imageUrl = `${baseUrl}?q=${quality}`;
+ * ```
+ */
+export function getConnectionAwareQuality(): number {
+  // SSR fallback
+  if (typeof navigator === 'undefined') {
+    return QUALITY_PRESETS.default;
+  }
+
+  const nav = navigator as NavigatorWithConnection;
+  const connection = nav.connection;
+
+  // No Network Information API support
+  if (!connection) {
+    return QUALITY_PRESETS.default;
+  }
+
+  // User has enabled data saver - respect their preference
+  if (connection.saveData) {
+    return QUALITY_PRESETS.saveData;
+  }
+
+  // Adjust based on effective connection type
+  const effectiveType = connection.effectiveType;
+  if (effectiveType && effectiveType in QUALITY_PRESETS) {
+    return QUALITY_PRESETS[effectiveType];
+  }
+
+  return QUALITY_PRESETS.default;
+}
+
+/**
+ * Check if the user prefers reduced data usage.
+ *
+ * @returns true if Save-Data is enabled or connection is slow
+ */
+export function prefersReducedData(): boolean {
+  if (typeof navigator === 'undefined') {
+    return false;
+  }
+
+  const nav = navigator as NavigatorWithConnection;
+  const connection = nav.connection;
+
+  if (!connection) {
+    return false;
+  }
+
+  return (
+    connection.saveData === true ||
+    connection.effectiveType === 'slow-2g' ||
+    connection.effectiveType === '2g'
+  );
+}

package/lib/markdown-utils.ts

@@ -0,0 +1,368 @@
+/**
+ * Markdown Parsing Utilities
+ *
+ * Three implementations showing the progression from naive to production-ready:
+ * - v1 (Naive): Direct call, crashes on bad input
+ * - v2 (Defensive): Try-catch with null fallback
+ * - v3 (Robust): Result type, validation, sanitization
+ *
+ * The robust version (v3) is exported as the default `parseMarkdown`.
+ */
+
+import type { MDTree } from '@repo/markdown-wasm';
+import { mdToJSON } from '@repo/markdown-wasm';
+
+import { err, ok, type Result } from './result';
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+/**
+ * Error codes for markdown parsing failures.
+ */
+export const ParseErrorCode = {
+  INVALID_INPUT: 'INVALID_INPUT',
+  EMPTY_CONTENT: 'EMPTY_CONTENT',
+  PARSE_FAILED: 'PARSE_FAILED',
+  CONTENT_TOO_LONG: 'CONTENT_TOO_LONG',
+  NESTED_TOO_DEEP: 'NESTED_TOO_DEEP',
+} as const;
+
+export type ParseErrorCode = (typeof ParseErrorCode)[keyof typeof ParseErrorCode];
+
+/**
+ * Structured error for markdown parsing failures.
+ */
+export interface ParseError {
+  code: ParseErrorCode;
+  message: string;
+  cause?: Error;
+}
+
+/**
+ * Options for robust markdown parsing.
+ */
+export interface ParseOptions {
+  /**
+   * Maximum content length in characters.
+   * @default 500000 (500KB of text, ~100K words)
+   */
+  maxLength?: number;
+
+  /**
+   * Whether to sanitize XSS attempts in the output.
+   * @default true
+   */
+  sanitize?: boolean;
+
+  /**
+   * Whether to allow empty content.
+   * @default false
+   */
+  allowEmpty?: boolean;
+}
+
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+
+const DEFAULT_MAX_LENGTH = 500_000; // 500KB of text
+
+/**
+ * Patterns that indicate potential XSS attempts in markdown.
+ * These are checked in raw content before parsing.
+ */
+const XSS_PATTERNS = [
+  /<script\b/i,
+  /javascript:/i,
+  /on\w+\s*=/i, // onclick=, onerror=, etc.
+  /data:/i, // data: URIs can be dangerous
+  /vbscript:/i,
+] as const;
+
+// -----------------------------------------------------------------------------
+// V1: Naive Implementation
+// -----------------------------------------------------------------------------
+
+/**
+ * Naive markdown parser - crashes on bad input.
+ *
+ * DO NOT USE IN PRODUCTION. This is for demonstration only.
+ *
+ * Problems:
+ * - No input validation
+ * - No error handling
+ * - Will crash the entire app on malformed input
+ * - No protection against XSS
+ * - No content limits
+ *
+ * @example
+ * ```ts
+ * // This crashes if content is null, undefined, or malformed
+ * const ast = parseMarkdownV1(userInput);
+ * ```
+ */
+export function parseMarkdownV1(content: string): MDTree {
+  return mdToJSON(content);
+}
+
+// -----------------------------------------------------------------------------
+// V2: Defensive Implementation
+// -----------------------------------------------------------------------------
+
+/**
+ * Defensive markdown parser - catches errors but loses context.
+ *
+ * Better than v1 but still problematic:
+ * - Returns null on any error (loses error details)
+ * - Caller can't distinguish between empty content and parse failure
+ * - Still no XSS protection
+ * - Still no content limits
+ *
+ * @example
+ * ```ts
+ * const ast = parseMarkdownV2(userInput);
+ * if (!ast) {
+ *   // What went wrong? We don't know.
+ *   return <ErrorFallback />;
+ * }
+ * ```
+ */
+export function parseMarkdownV2(content: string): MDTree | null {
+  try {
+    // Basic null check
+    if (content == null) {
+      return null;
+    }
+    return mdToJSON(content);
+  } catch {
+    return null;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// V3: Robust Implementation
+// -----------------------------------------------------------------------------
+
+/**
+ * Creates a ParseError with the given code and message.
+ */
+function createParseError(code: ParseErrorCode, message: string, cause?: Error): ParseError {
+  return { code, message, cause };
+}
+
+/**
+ * Checks content for potential XSS patterns.
+ * Returns the first matched pattern or null if clean.
+ */
+function detectXssPattern(content: string): RegExp | null {
+  for (const pattern of XSS_PATTERNS) {
+    if (pattern.test(content)) {
+      return pattern;
+    }
+  }
+  return null;
+}
+
+/**
+ * Sanitizes content by removing dangerous patterns.
+ * This is a basic sanitizer; production should use DOMPurify.
+ */
+function sanitizeContent(content: string): string {
+  let sanitized = content;
+
+  // Remove script tags
+  sanitized = sanitized.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
+
+  // Remove javascript: and vbscript: URLs
+  sanitized = sanitized.replace(/javascript:/gi, 'removed:');
+  sanitized = sanitized.replace(/vbscript:/gi, 'removed:');
+
+  // Remove event handlers (onclick, onerror, etc.)
+  sanitized = sanitized.replace(/\bon\w+\s*=\s*["'][^"']*["']/gi, '');
+  sanitized = sanitized.replace(/\bon\w+\s*=\s*\S+/gi, '');
+
+  return sanitized;
+}
+
+/**
+ * Robust markdown parser - production-ready with full error context.
+ *
+ * Features:
+ * - Input validation with specific error codes
+ * - Result type for explicit error handling
+ * - XSS pattern detection and optional sanitization
+ * - Content length limits
+ * - Preserves error context for debugging
+ *
+ * @param content - Markdown string to parse
+ * @param options - Parsing options
+ * @returns Result containing the AST or a structured error
+ *
+ * @example
+ * ```ts
+ * const result = parseMarkdownV3(userInput);
+ *
+ * if (!result.ok) {
+ *   switch (result.error.code) {
+ *     case 'INVALID_INPUT':
+ *       return <InvalidInputError message={result.error.message} />;
+ *     case 'CONTENT_TOO_LONG':
+ *       return <ContentTooLongError />;
+ *     case 'PARSE_FAILED':
+ *       console.error('Parse error:', result.error.cause);
+ *       return <ParseError />;
+ *     default:
+ *       return <GenericError />;
+ *   }
+ * }
+ *
+ * return <MarkdownRenderer ast={result.value} />;
+ * ```
+ */
+export function parseMarkdownV3(
+  content: string,
+  options: ParseOptions = {}
+): Result<MDTree, ParseError> {
+  const { maxLength = DEFAULT_MAX_LENGTH, sanitize = true, allowEmpty = false } = options;
+
+  // 1. Validate input type
+  if (content === null || content === undefined) {
+    return err(
+      createParseError(
+        ParseErrorCode.INVALID_INPUT,
+        `Content must be a string, received ${content === null ? 'null' : 'undefined'}`
+      )
+    );
+  }
+
+  if (typeof content !== 'string') {
+    return err(
+      createParseError(
+        ParseErrorCode.INVALID_INPUT,
+        `Content must be a string, received ${typeof content}`
+      )
+    );
+  }
+
+  // 2. Handle empty content
+  const trimmed = content.trim();
+  if (trimmed.length === 0 && !allowEmpty) {
+    return err(
+      createParseError(ParseErrorCode.EMPTY_CONTENT, 'Content is empty or contains only whitespace')
+    );
+  }
+
+  // 3. Check content length
+  if (content.length > maxLength) {
+    return err(
+      createParseError(
+        ParseErrorCode.CONTENT_TOO_LONG,
+        `Content exceeds maximum length of ${maxLength.toLocaleString()} characters ` +
+          `(received ${content.length.toLocaleString()})`
+      )
+    );
+  }
+
+  // 4. Check for XSS patterns
+  const xssPattern = detectXssPattern(content);
+  if (xssPattern) {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(
+        `[parseMarkdownV3] XSS pattern detected: ${xssPattern.toString()}`,
+        sanitize ? 'Content will be sanitized.' : 'Sanitization is disabled!'
+      );
+    }
+  }
+
+  // 5. Optionally sanitize content
+  const processedContent = sanitize ? sanitizeContent(content) : content;
+
+  // 6. Parse markdown with error handling
+  try {
+    const ast = mdToJSON(processedContent);
+    return ok(ast);
+  } catch (error) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return err(
+      createParseError(
+        ParseErrorCode.PARSE_FAILED,
+        `Failed to parse markdown: ${cause.message}`,
+        cause
+      )
+    );
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Default Export
+// -----------------------------------------------------------------------------
+
+/**
+ * Production-ready markdown parser.
+ *
+ * This is an alias for `parseMarkdownV3` - the robust implementation
+ * with validation, sanitization, and Result-based error handling.
+ *
+ * @example
+ * ```ts
+ * import { parseMarkdown } from '@/lib/markdown-utils';
+ *
+ * const result = parseMarkdown(content);
+ * if (!result.ok) {
+ *   // Handle error with full context
+ *   console.error(`[${result.error.code}] ${result.error.message}`);
+ *   return null;
+ * }
+ * return result.value;
+ * ```
+ */
+export const parseMarkdown = parseMarkdownV3;
+
+// -----------------------------------------------------------------------------
+// Utility Functions
+// -----------------------------------------------------------------------------
+
+/**
+ * Checks if content is safe markdown (no XSS patterns detected).
+ *
+ * @param content - Markdown string to check
+ * @returns true if no XSS patterns detected
+ */
+export function isSafeMarkdown(content: string): boolean {
+  return detectXssPattern(content) === null;
+}
+
+/**
+ * Estimates the word count of markdown content.
+ * Useful for content length limits and reading time estimates.
+ *
+ * @param content - Markdown string to count
+ * @returns Estimated word count
+ */
+export function estimateWordCount(content: string): number {
+  // Remove markdown syntax for more accurate count
+  const plainText = content
+    .replace(/#+\s/g, '') // Remove headings
+    .replace(/\*\*|__|~~|`/g, '') // Remove formatting
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // Convert links to text
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, '') // Remove images
+    .replace(/```[\s\S]*?```/g, '') // Remove code blocks
+    .replace(/`[^`]+`/g, ''); // Remove inline code
+
+  const words = plainText.trim().split(/\s+/).filter(Boolean);
+  return words.length;
+}
+
+/**
+ * Estimates reading time for markdown content.
+ *
+ * @param content - Markdown string
+ * @param wordsPerMinute - Reading speed (default 200 WPM)
+ * @returns Reading time in minutes
+ */
+export function estimateReadingTime(content: string, wordsPerMinute = 200): number {
+  const wordCount = estimateWordCount(content);
+  return Math.ceil(wordCount / wordsPerMinute);
+}