jamdesk 1.0.0

package/vendored/components/mdx/Color.tsx

@@ -0,0 +1,244 @@
+'use client';
+
+import { createContext, useContext, type ReactNode } from 'react';
+
+type ColorValue = string | { light: string; dark: string };
+
+interface ColorItemProps {
+  name?: string;
+  value: ColorValue;
+}
+
+interface ColorRowProps {
+  title?: string;
+  children: ReactNode;
+}
+
+interface ColorProps {
+  variant?: 'compact' | 'table';
+  children: ReactNode;
+}
+
+// Context to pass variant down to children
+const ColorContext = createContext<{ variant: 'compact' | 'table' }>({ variant: 'compact' });
+
+/**
+ * Parse a color string and return RGB values
+ * Supports: hex (#RGB, #RRGGBB, #RRGGBBAA), rgb(), rgba()
+ */
+function parseColor(color: string): { r: number; g: number; b: number } | null {
+  const trimmed = color.trim().toLowerCase();
+
+  // Handle hex colors
+  if (trimmed.startsWith('#')) {
+    const hex = trimmed.slice(1);
+    let r: number, g: number, b: number;
+
+    if (hex.length === 3 || hex.length === 4) {
+      // #RGB or #RGBA
+      r = parseInt(hex[0] + hex[0], 16);
+      g = parseInt(hex[1] + hex[1], 16);
+      b = parseInt(hex[2] + hex[2], 16);
+    } else if (hex.length === 6 || hex.length === 8) {
+      // #RRGGBB or #RRGGBBAA
+      r = parseInt(hex.slice(0, 2), 16);
+      g = parseInt(hex.slice(2, 4), 16);
+      b = parseInt(hex.slice(4, 6), 16);
+    } else {
+      return null;
+    }
+
+    if (isNaN(r) || isNaN(g) || isNaN(b)) return null;
+    return { r, g, b };
+  }
+
+  // Handle rgb() and rgba()
+  const rgbMatch = trimmed.match(/rgba?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+  if (rgbMatch) {
+    return {
+      r: parseInt(rgbMatch[1], 10),
+      g: parseInt(rgbMatch[2], 10),
+      b: parseInt(rgbMatch[3], 10),
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Calculate relative luminance and determine if text should be light or dark
+ * Uses WCAG formula for contrast
+ */
+function shouldUseLightText(color: string): boolean {
+  const rgb = parseColor(color);
+  if (!rgb) return false;
+
+  // Calculate relative luminance using WCAG formula
+  const [r, g, b] = [rgb.r, rgb.g, rgb.b].map((c) => {
+    const normalized = c / 255;
+    return normalized <= 0.03928
+      ? normalized / 12.92
+      : Math.pow((normalized + 0.055) / 1.055, 2.4);
+  });
+
+  const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  return luminance < 0.5;
+}
+
+/**
+ * Get display value for a color (for showing in the UI)
+ */
+function getDisplayValue(value: ColorValue): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  return value.light;
+}
+
+/**
+ * ColorItem - Individual color swatch
+ */
+export function ColorItem({ name, value }: ColorItemProps) {
+  const { variant } = useContext(ColorContext);
+  const isThemeAware = typeof value === 'object';
+  const displayValue = getDisplayValue(value);
+
+  // CSS variables for theme-aware colors
+  const cssVars = isThemeAware
+    ? ({
+        '--color-swatch-light': value.light,
+        '--color-swatch-dark': value.dark,
+      } as React.CSSProperties)
+    : {};
+
+  const swatchColor = isThemeAware ? 'var(--color-swatch-light)' : value;
+  const lightTextOnLight = isThemeAware ? shouldUseLightText(value.light) : shouldUseLightText(value as string);
+  const lightTextOnDark = isThemeAware ? shouldUseLightText(value.dark) : lightTextOnLight;
+
+  if (variant === 'table') {
+    return (
+      <div
+        className="color-item-table flex items-center gap-3 py-2 px-3 border-b border-[var(--color-border)] last:border-b-0 cursor-pointer"
+        style={cssVars}
+        data-copy-text={displayValue}
+        title="Click to copy"
+      >
+        {/* Color swatch */}
+        <div
+          className="color-swatch w-8 h-8 rounded-md border border-black/10 flex-shrink-0"
+          style={{ backgroundColor: swatchColor }}
+        />
+        {/* Name */}
+        <span className="color-name flex-1 text-sm font-medium text-[var(--color-text-primary)]">
+          {name}
+        </span>
+        {/* Value */}
+        <code className="color-value text-xs font-mono text-[var(--color-text-secondary)]">
+          {displayValue}
+        </code>
+        {/* Copy icon */}
+        <i className="fa-regular fa-copy text-xs text-[var(--color-text-muted)]" aria-hidden="true" />
+      </div>
+    );
+  }
+
+  // Compact variant
+  return (
+    <div
+      className="color-item-compact flex flex-col rounded-lg overflow-hidden border border-[var(--color-border)] cursor-pointer"
+      style={cssVars}
+      data-copy-text={displayValue}
+      title="Click to copy"
+    >
+      {/* Color swatch area */}
+      <div
+        className="color-swatch h-20 flex items-end justify-start p-2"
+        style={{ backgroundColor: swatchColor }}
+      >
+        {isThemeAware && (
+          <span
+            className="color-theme-indicator text-xs px-1.5 py-0.5 rounded bg-black/20"
+            style={{
+              color: lightTextOnLight ? '#fff' : '#000',
+            }}
+          >
+            Theme
+          </span>
+        )}
+      </div>
+      {/* Info area */}
+      <div className="color-info p-3 bg-[var(--color-bg-primary)]">
+        {name && (
+          <div className="color-name text-sm font-medium text-[var(--color-text-primary)] mb-1">
+            {name}
+          </div>
+        )}
+        <code className="color-value text-xs font-mono text-[var(--color-text-secondary)]">
+          {displayValue}
+        </code>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * ColorRow - Group of colors with a title (for table variant)
+ */
+export function ColorRow({ title, children }: ColorRowProps) {
+  return (
+    <div className="color-row mb-4 last:mb-0">
+      {title && (
+        <div className="color-row-title text-sm font-semibold text-[var(--color-text-primary)] mb-2 px-3">
+          {title}
+        </div>
+      )}
+      <div className="color-row-items rounded-lg border border-[var(--color-border)] overflow-hidden">
+        {children}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Color - Container component for displaying color palettes
+ *
+ * @example Compact variant (grid layout)
+ * <Color variant="compact">
+ *   <Color.Item name="Primary" value="#3b82f6" />
+ *   <Color.Item name="Secondary" value="#6366f1" />
+ * </Color>
+ *
+ * @example Table variant (grouped rows)
+ * <Color variant="table">
+ *   <Color.Row title="Primary Colors">
+ *     <Color.Item name="Blue" value="#3b82f6" />
+ *   </Color.Row>
+ * </Color>
+ *
+ * @example Theme-aware colors
+ * <Color.Item name="Background" value={{ light: "#ffffff", dark: "#000000" }} />
+ */
+export function Color({ variant = 'compact', children }: ColorProps) {
+  const isCompact = variant === 'compact';
+
+  return (
+    <ColorContext.Provider value={{ variant }}>
+      <div
+        className={`color-palette my-6 not-prose ${
+          isCompact ? 'grid gap-4' : ''
+        }`}
+        style={
+          isCompact
+            ? { gridTemplateColumns: 'repeat(auto-fill, minmax(140px, 1fr))' }
+            : undefined
+        }
+      >
+        {children}
+      </div>
+    </ColorContext.Provider>
+  );
+}
+
+// Attach sub-components
+Color.Item = ColorItem;
+Color.Row = ColorRow;

package/vendored/components/mdx/Columns.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+
+interface ColumnsProps {
+  children: React.ReactNode;
+  /** The number of columns per row. Accepts values from 1 to 4. Default: 2 */
+  cols?: number;
+  className?: string;
+}
+
+/**
+ * Columns component for displaying multiple Card components together in a responsive grid.
+ * The grid automatically adapts to smaller screens.
+ *
+ * @example
+ * <Columns cols={2}>
+ *   <Card title="Get started">Set up your project</Card>
+ *   <Card title="API reference">Explore endpoints</Card>
+ * </Columns>
+ */
+// Responsive grid classes: mobile (1 col), tablet (2 cols max), desktop (full count)
+const GRID_CLASSES: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-1 md:grid-cols-2',
+  3: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+  4: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-4',
+};
+
+export function Columns({ children, cols = 2, className = '' }: ColumnsProps) {
+  const gridCols = Math.min(Math.max(cols, 1), 4);
+  const responsiveClass = GRID_CLASSES[gridCols];
+
+  return (
+    <div className={`grid gap-4 my-4 not-prose [&>*]:my-0 [&>div]:my-0 [&>a]:my-0 ${responsiveClass} ${className}`.trim()}>
+      {children}
+    </div>
+  );
+}

package/vendored/components/mdx/Expandable.tsx

@@ -0,0 +1,37 @@
+'use client';
+
+import { useState } from 'react';
+
+interface ExpandableProps {
+  title: string;
+  children: React.ReactNode;
+  defaultOpen?: boolean;
+}
+
+/**
+ * Expandable component - a collapsible section.
+ * Component for expandable content.
+ */
+export function Expandable({ title, children, defaultOpen = false }: ExpandableProps) {
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+
+  return (
+    <div className="border border-[var(--color-border)] rounded-lg my-4 overflow-hidden not-prose">
+      <button
+        className="w-full px-4 py-3 flex items-center gap-2 text-left bg-theme-bg-secondary hover:bg-theme-bg-tertiary transition-colors"
+        onClick={() => setIsOpen(!isOpen)}
+      >
+        <span className="font-medium text-theme-text-primary capitalize">{title}</span>
+        <i
+          className={`fa-solid fa-chevron-right text-[10px] text-[var(--color-text-muted)] transition-transform ${isOpen ? 'rotate-90' : ''}`}
+          aria-hidden="true"
+        />
+      </button>
+      {isOpen && (
+        <div className="px-4 py-3 border-t border-[var(--color-border)] text-sm leading-relaxed [&>p]:m-0 [&>p]:mb-3 [&>p:last-child]:mb-0 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0 [&>ul]:my-2 [&>ul]:ml-4 [&>ul]:list-disc [&>ol]:my-2 [&>ol]:ml-4 [&>ol]:list-decimal [&>li]:mb-1 [&>strong]:font-semibold [&>a]:text-[var(--color-accent)] [&>a]:underline">
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}

package/vendored/components/mdx/Frame.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+interface FrameProps {
+  children: React.ReactNode;
+  caption?: string;
+}
+
+/**
+ * Frame component - wraps content in a styled frame.
+ * Component for framed content/images.
+ */
+export function Frame({ children, caption }: FrameProps) {
+  const [isDark, setIsDark] = useState(false);
+
+  useEffect(() => {
+    // Check initial theme
+    setIsDark(document.documentElement.classList.contains('dark'));
+
+    // Watch for theme changes
+    const observer = new MutationObserver(() => {
+      setIsDark(document.documentElement.classList.contains('dark'));
+    });
+
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
+
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <figure className="my-6">
+      <div
+        className="frame-content rounded-lg overflow-x-auto p-2 [&_img]:!my-0 [&_img]:!rounded-md [&_p]:!my-0"
+        style={{
+          backgroundColor: isDark ? '#0f1419' : '#f8f9fa',
+          boxShadow: isDark
+            ? 'inset 0 0 0 0.5px rgba(107, 114, 128, 0.3)'
+            : 'inset 0 0 0 0.5px rgba(209, 213, 219, 0.8)'
+        }}
+      >
+        {children}
+      </div>
+      {caption && (
+        <figcaption className="mt-2 text-sm text-center text-theme-text-tertiary">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}

package/vendored/components/mdx/Icon.tsx

@@ -0,0 +1,132 @@
+import { getIconClass } from '@/lib/icon-utils';
+
+interface IconProps {
+  /**
+   * The icon to display. Options:
+   * - Font Awesome icon name (e.g., "flag", "circle-xmark")
+   * - URL to external icon (e.g., "https://example.com/icon.svg")
+   * - Path to icon file (e.g., "/images/icon.svg")
+   */
+  icon: string | React.ReactElement;
+  /** Font Awesome icon style */
+  iconType?: 'regular' | 'solid' | 'light' | 'thin' | 'sharp-solid' | 'duotone' | 'brands';
+  /** Color as hex code (#FF5733) or named color (red, blue, etc.) */
+  color?: string;
+  /** Size in pixels (default: 16) */
+  size?: number;
+  /** Custom CSS class */
+  className?: string;
+}
+
+/**
+ * Get color style from color prop
+ */
+function getColorStyle(color?: string): { style?: React.CSSProperties; className?: string } {
+  if (!color) return {};
+
+  // Hex code - use inline style
+  if (color.startsWith('#')) {
+    return { style: { color } };
+  }
+
+  // Named colors - map to Tailwind classes
+  const colorMap: Record<string, string> = {
+    'red': 'text-red-500',
+    'blue': 'text-blue-500',
+    'green': 'text-green-500',
+    'yellow': 'text-yellow-500',
+    'orange': 'text-orange-500',
+    'purple': 'text-purple-500',
+    'pink': 'text-pink-500',
+    'gray': 'text-gray-400',
+    'grey': 'text-gray-400',
+    'white': 'text-white',
+    'black': 'text-black',
+    'primary': 'text-theme-accent',
+  };
+
+  if (colorMap[color.toLowerCase()]) {
+    return { className: colorMap[color.toLowerCase()] };
+  }
+
+  // Try as direct color value
+  return { style: { color } };
+}
+
+/**
+ * Icon component for rendering icons in MDX content.
+ * Supports Font Awesome icons via CSS, SVG elements, URLs, and file paths.
+ *
+ * @example
+ * // Font Awesome icon by name
+ * <Icon icon="flag" size={32} />
+ *
+ * // Font Awesome with style
+ * <Icon icon="circle-xmark" iconType="solid" color="red" />
+ *
+ * // Hex color
+ * <Icon icon="repeat" color="#FF5733" />
+ *
+ * // External URL
+ * <Icon icon="https://example.com/icon.svg" size={24} />
+ *
+ * // Local file path
+ * <Icon icon="/images/custom-icon.svg" size={24} />
+ *
+ * // Inline SVG (JSX)
+ * <Icon icon={<svg viewBox="0 0 24 24"><path d="..."/></svg>} />
+ *
+ */
+export function Icon({ icon, iconType = 'solid', color, size = 16, className }: IconProps) {
+  const { style: colorStyle, className: colorClass } = getColorStyle(color);
+  const combinedClassName = `inline-block ${colorClass || ''} ${className || ''}`.trim();
+  const sizeStyle = { width: size, height: size };
+
+  // Case 1: JSX SVG element passed directly
+  if (typeof icon !== 'string') {
+    // It's a React element (SVG)
+    return (
+      <span
+        className={combinedClassName}
+        style={{ ...sizeStyle, ...colorStyle, display: 'inline-flex', alignItems: 'center' }}
+      >
+        {icon}
+      </span>
+    );
+  }
+
+  // Case 2: URL to external icon
+  if (icon.startsWith('http://') || icon.startsWith('https://')) {
+    return (
+      <img
+        src={icon}
+        alt=""
+        className={combinedClassName}
+        style={{ ...sizeStyle, ...colorStyle }}
+      />
+    );
+  }
+
+  // Case 3: Local file path (starts with / or ./)
+  if (icon.startsWith('/') || icon.startsWith('./')) {
+    return (
+      <img
+        src={icon}
+        alt=""
+        className={combinedClassName}
+        style={{ ...sizeStyle, ...colorStyle }}
+      />
+    );
+  }
+
+  // Case 4: Font Awesome icon via CSS class
+  const faClass = getIconClass(icon);
+
+  return (
+    <i
+      className={`${faClass} ${combinedClassName}`}
+      style={{ ...sizeStyle, ...colorStyle }}
+      aria-hidden="true"
+    />
+  );
+}

package/vendored/components/mdx/Latex.tsx

@@ -0,0 +1,75 @@
+import katex from 'katex';
+import type { ReactNode } from 'react';
+
+interface LatexProps {
+  children: ReactNode;
+  block?: boolean;
+}
+
+/**
+ * Latex component for rendering mathematical equations using KaTeX.
+ *
+ * Supports two modes:
+ * - Inline (default): Renders within text flow
+ * - Block: Centered display mode for standalone equations
+ *
+ * Security: Uses dangerouslySetInnerHTML with KaTeX output. This is safe
+ * because KaTeX only processes LaTeX math syntax (not arbitrary HTML).
+ * KaTeX is designed to be XSS-safe and is widely used by documentation platforms.
+ *
+ * @example
+ * // Inline math
+ * <Latex>E = mc^2</Latex>
+ *
+ * // Block/display math
+ * <Latex block>
+ *   \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
+ * </Latex>
+ */
+export function Latex({ children, block = false }: LatexProps) {
+  // Convert children to string - handles string, array, or other ReactNode types
+  const latex = extractLatexString(children);
+
+  try {
+    // KaTeX.renderToString is safe - it only parses LaTeX math syntax,
+    // not arbitrary HTML. Invalid LaTeX produces error messages, not XSS.
+    const html = katex.renderToString(latex, {
+      displayMode: block,
+      throwOnError: false, // Render error message instead of throwing
+      errorColor: '#cc0000',
+      trust: false, // Don't allow potentially dangerous commands like \url
+      strict: 'warn', // Log warnings for unsupported commands
+    });
+
+    return (
+      <span
+        className={block ? 'katex-display block my-4 text-center overflow-x-auto' : 'katex-inline'}
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    );
+  } catch (error) {
+    // Fallback for truly unexpected errors
+    console.error('[Latex] Rendering error:', error);
+    return (
+      <span className="text-red-500 font-mono text-sm bg-red-50 dark:bg-red-950 px-1 rounded">
+        LaTeX Error: {latex.slice(0, 50)}{latex.length > 50 ? '...' : ''}
+      </span>
+    );
+  }
+}
+
+/**
+ * Extract a string from ReactNode children.
+ * Handles strings, arrays, and stringifies other types.
+ */
+function extractLatexString(children: ReactNode): string {
+  if (typeof children === 'string') {
+    return children;
+  }
+  if (Array.isArray(children)) {
+    return children.map(child =>
+      typeof child === 'string' ? child : String(child ?? '')
+    ).join('');
+  }
+  return String(children ?? '');
+}