@fragments-sdk/cli 0.2.2

package/src/viewer/components/ContractPanel.tsx

@@ -0,0 +1,234 @@
+/**
+ * ContractPanel component - displays SegmentContract metadata for AI agents.
+ * Shows propsSummary, scenarioTags, bans, and a11yRules.
+ */
+
+import { memo } from 'react';
+import type { SegmentContract } from '../../core/index.js';
+
+interface ContractPanelProps {
+  contract?: SegmentContract;
+  componentName: string;
+}
+
+export const ContractPanel = memo(function ContractPanel({
+  contract,
+  componentName,
+}: ContractPanelProps) {
+  // Empty state when no contract metadata
+  if (!contract || isContractEmpty(contract)) {
+    return (
+      <div className="p-6 text-center">
+        <div className="text-tertiary mb-4">
+          <svg
+            className="w-12 h-12 mx-auto mb-4 opacity-50"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+            />
+          </svg>
+          <p className="text-sm font-medium">No contract metadata</p>
+        </div>
+        <p className="text-xs text-quaternary mb-4">
+          Add a <code className="bg-[--bg-hover] px-1 py-0.5 rounded">contract</code> field to the segment definition to enable AI agent features.
+        </p>
+        <div className="text-left bg-[--bg-hover] rounded-lg p-4 text-xs font-mono">
+          <pre className="text-quaternary">{`contract: {
+  propsSummary: ['variant: primary|secondary'],
+  scenarioTags: ['form.submit', 'action.primary'],
+  a11yRules: ['A11Y_BTN_LABEL'],
+}`}</pre>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-4 space-y-6 text-sm">
+      {/* Props Summary */}
+      {contract.propsSummary && contract.propsSummary.length > 0 && (
+        <Section title="Props Summary">
+          <div className="overflow-x-auto">
+            <table className="w-full text-xs border-collapse">
+              <thead>
+                <tr className="border-b border-[--border]">
+                  <th className="text-left py-2 pr-4 font-medium text-tertiary">Name</th>
+                  <th className="text-left py-2 pr-4 font-medium text-tertiary">Type</th>
+                  <th className="text-left py-2 font-medium text-tertiary">Description</th>
+                </tr>
+              </thead>
+              <tbody>
+                {contract.propsSummary.map((prop, i) => {
+                  const parsed = parsePropSummary(prop);
+                  return (
+                    <tr key={i} className="border-b border-[--border-subtle] last:border-b-0">
+                      <td className="py-2 pr-4 align-top">
+                        <code className="text-xs font-medium text-primary">{parsed.name}</code>
+                      </td>
+                      <td className="py-2 pr-4 align-top">
+                        <code className="text-xs text-purple-600 dark:text-purple-400">{parsed.type}</code>
+                      </td>
+                      <td className="py-2 align-top text-secondary">{parsed.description}</td>
+                    </tr>
+                  );
+                })}
+              </tbody>
+            </table>
+          </div>
+        </Section>
+      )}
+
+      {/* Scenario Tags */}
+      {contract.scenarioTags && contract.scenarioTags.length > 0 && (
+        <Section title="Scenario Tags" subtitle="Used by fragments_suggest for AI queries">
+          <div className="flex flex-wrap gap-2">
+            {contract.scenarioTags.map((tag, i) => (
+              <span
+                key={i}
+                className="inline-flex items-center px-2.5 py-1 rounded-full text-xs font-medium bg-blue-500/10 text-blue-500 border border-blue-500/20"
+              >
+                {tag}
+              </span>
+            ))}
+          </div>
+        </Section>
+      )}
+
+      {/* Accessibility Rules */}
+      {contract.a11yRules && contract.a11yRules.length > 0 && (
+        <Section title="Accessibility Rules">
+          <div className="space-y-2">
+            {contract.a11yRules.map((rule, i) => (
+              <div
+                key={i}
+                className="flex items-center gap-2 p-2 bg-[--bg-hover] rounded"
+              >
+                <span className="text-green-500">
+                  <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+                  </svg>
+                </span>
+                <code className="text-xs text-secondary">{rule}</code>
+              </div>
+            ))}
+          </div>
+        </Section>
+      )}
+
+      {/* Bans */}
+      {contract.bans && contract.bans.length > 0 && (
+        <Section title="Usage Bans" subtitle="Patterns to avoid">
+          <div className="space-y-2">
+            {contract.bans.map((ban, i) => (
+              <div
+                key={i}
+                className="p-3 bg-amber-500/10 border border-amber-500/20 rounded"
+              >
+                <div className="flex items-center gap-2 mb-1">
+                  <span className="text-amber-500">
+                    <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" />
+                    </svg>
+                  </span>
+                  <code className="text-xs text-amber-600 dark:text-amber-400">
+                    {ban.pattern}
+                  </code>
+                </div>
+                <p className="text-xs text-tertiary pl-6">{ban.message}</p>
+              </div>
+            ))}
+          </div>
+        </Section>
+      )}
+
+      {/* Empty sections message */}
+      {isPartialContract(contract) && (
+        <div className="text-xs text-quaternary p-3 bg-[--bg-hover] rounded">
+          Tip: Add more contract fields to help AI agents better understand this component.
+        </div>
+      )}
+    </div>
+  );
+});
+
+// Helper component for consistent section styling
+interface SectionProps {
+  title: string;
+  subtitle?: string;
+  children: React.ReactNode;
+}
+
+function Section({ title, subtitle, children }: SectionProps) {
+  return (
+    <div>
+      <h3 className="text-xs font-semibold text-primary mb-2 flex items-center gap-2">
+        {title}
+        {subtitle && (
+          <span className="font-normal text-quaternary">({subtitle})</span>
+        )}
+      </h3>
+      {children}
+    </div>
+  );
+}
+
+// Check if contract is empty or has no meaningful content
+function isContractEmpty(contract: SegmentContract): boolean {
+  return (
+    (!contract.propsSummary || contract.propsSummary.length === 0) &&
+    (!contract.scenarioTags || contract.scenarioTags.length === 0) &&
+    (!contract.a11yRules || contract.a11yRules.length === 0) &&
+    (!contract.bans || contract.bans.length === 0)
+  );
+}
+
+// Check if contract has some but not all fields
+function isPartialContract(contract: SegmentContract): boolean {
+  const fieldCount = [
+    contract.propsSummary?.length ?? 0,
+    contract.scenarioTags?.length ?? 0,
+    contract.a11yRules?.length ?? 0,
+    contract.bans?.length ?? 0,
+  ].filter(n => n > 0).length;
+
+  return fieldCount > 0 && fieldCount < 3;
+}
+
+// Parse a prop summary string like "name: type - description" or "name: type (default: value)"
+function parsePropSummary(prop: string): { name: string; type: string; description: string } {
+  // Try to match "name: type - description" format
+  const colonIndex = prop.indexOf(':');
+  if (colonIndex === -1) {
+    return { name: prop, type: '', description: '' };
+  }
+
+  const name = prop.slice(0, colonIndex).trim();
+  const rest = prop.slice(colonIndex + 1).trim();
+
+  // Check for " - description" pattern
+  const dashIndex = rest.indexOf(' - ');
+  if (dashIndex !== -1) {
+    const type = rest.slice(0, dashIndex).trim();
+    const description = rest.slice(dashIndex + 3).trim();
+    return { name, type, description };
+  }
+
+  // Check for "(default: value)" or "(default: value) description" pattern
+  const defaultMatch = rest.match(/^([^(]+)(\(default:\s*[^)]+\))(.*)$/);
+  if (defaultMatch) {
+    const type = defaultMatch[1].trim();
+    const defaultInfo = defaultMatch[2];
+    const extraDesc = defaultMatch[3].trim();
+    const description = extraDesc ? `${defaultInfo} ${extraDesc}` : defaultInfo;
+    return { name, type, description };
+  }
+
+  // Just type, no description
+  return { name, type: rest, description: '' };
+}

package/src/viewer/components/ErrorBoundary.tsx

@@ -0,0 +1,85 @@
+import { Component, type ReactNode, type ErrorInfo } from 'react';
+import { ErrorIcon, RefreshIcon } from './Icons.js';
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  componentName?: string;
+  onRetry?: () => void;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+  errorInfo: ErrorInfo | null;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false, error: null, errorInfo: null };
+  }
+
+  static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState> {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    // Log error to console with full stack trace
+    console.error('Component Error:', error);
+    console.error('Component Stack:', errorInfo.componentStack);
+
+    this.setState({ errorInfo });
+  }
+
+  handleRetry = () => {
+    this.setState({ hasError: false, error: null, errorInfo: null });
+    this.props.onRetry?.();
+  };
+
+  render() {
+    if (this.state.hasError) {
+      const { componentName } = this.props;
+      const { error, errorInfo } = this.state;
+
+      return (
+        <div className="p-6 rounded-xl border-2 border-red-300 dark:border-red-700 bg-red-50 dark:bg-red-950">
+          <div className="flex items-start gap-3">
+            <ErrorIcon className="w-6 h-6 text-red-600 dark:text-red-400 flex-shrink-0 mt-0.5" />
+            <div className="flex-1 min-w-0">
+              <h3 className="text-sm font-semibold text-red-900 dark:text-red-100 mb-1">
+                {componentName ? `Error rendering ${componentName}` : 'Component Error'}
+              </h3>
+
+              {error && (
+                <p className="text-sm text-red-800 dark:text-red-200 mb-3 font-mono">
+                  {error.message}
+                </p>
+              )}
+
+              {errorInfo?.componentStack && (
+                <details className="mb-4">
+                  <summary className="text-xs text-red-700 dark:text-red-300 cursor-pointer hover:text-red-900 dark:hover:text-red-100 transition-colors">
+                    Show stack trace
+                  </summary>
+                  <pre className="mt-2 p-3 text-[10px] font-mono bg-red-100 dark:bg-red-900 rounded-lg overflow-x-auto text-red-800 dark:text-red-200 whitespace-pre-wrap">
+                    {error?.stack || errorInfo.componentStack}
+                  </pre>
+                </details>
+              )}
+
+              <button
+                onClick={this.handleRetry}
+                className="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-md bg-red-600 text-white hover:bg-red-700 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-red-500 focus-visible:ring-offset-2"
+              >
+                <RefreshIcon className="w-3.5 h-3.5" />
+                Retry
+              </button>
+            </div>
+          </div>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}

package/src/viewer/components/FigmaEmbed.tsx

@@ -0,0 +1,231 @@
+import { useRef, useEffect, useState, useMemo, useCallback } from "react";
+import { FigmaIcon } from "./Icons.js";
+
+interface FigmaEmbedProps {
+  /** Current Figma URL to display */
+  figmaUrl: string;
+  /** All Figma URLs for the current component (for preloading) */
+  allFigmaUrls?: string[];
+  zoom?: number;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+interface ParsedFigmaUrl {
+  fileKey: string;
+  nodeId?: string;
+  fullUrl: string;
+}
+
+/**
+ * Parse a Figma URL to extract file key and node ID.
+ */
+function parseFigmaUrl(figmaUrl: string): ParsedFigmaUrl | null {
+  try {
+    const urlPattern = /figma\.com\/(?:file|design)\/([^\/]+)\/[^?]*(?:\?.*node-id=([^&]+))?/i;
+    const match = figmaUrl.match(urlPattern);
+
+    if (!match) return null;
+
+    const fileKey = match[1];
+    const nodeId = match[2] ? decodeURIComponent(match[2]) : undefined;
+
+    return { fileKey, nodeId, fullUrl: figmaUrl };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a Figma embed URL.
+ */
+function buildEmbedUrl(fileKey: string, nodeId?: string): string {
+  let embedUrl = `https://embed.figma.com/design/${fileKey}?embed-host=segments`;
+
+  if (nodeId) {
+    const embedNodeId = nodeId.replace(/:/g, "-");
+    embedUrl += `&node-id=${embedNodeId}`;
+  }
+
+  embedUrl += "&hide-ui=1";
+  return embedUrl;
+}
+
+/**
+ * Get a unique key for a Figma URL (used for iframe identification)
+ */
+function getUrlKey(figmaUrl: string): string {
+  const parsed = parseFigmaUrl(figmaUrl);
+  if (!parsed) return figmaUrl;
+  return `${parsed.fileKey}:${parsed.nodeId || "default"}`;
+}
+
+/**
+ * FigmaEmbed component with iframe pooling for instant variant switching.
+ *
+ * Strategy: Pre-load iframes for ALL variants of the current component.
+ * When switching variants, we just show/hide the appropriate iframe.
+ * This makes switching instantaneous since iframes are already loaded.
+ *
+ * The design embed doesn't support postMessage navigation (only prototype
+ * embeds do), so this pooling approach is the only way to achieve instant
+ * switching.
+ */
+export function FigmaEmbed({ figmaUrl, allFigmaUrls, zoom = 100, className, style }: FigmaEmbedProps) {
+  // Track loaded iframes
+  const [loadedUrls, setLoadedUrls] = useState<Set<string>>(new Set());
+  const [error, setError] = useState<string | null>(null);
+
+  // Parse the current URL
+  const currentParsed = useMemo(() => parseFigmaUrl(figmaUrl), [figmaUrl]);
+  const currentKey = useMemo(() => getUrlKey(figmaUrl), [figmaUrl]);
+
+  // Get all URLs to preload (deduplicated)
+  const urlsToPreload = useMemo(() => {
+    const urls = allFigmaUrls && allFigmaUrls.length > 0 ? allFigmaUrls : [figmaUrl];
+    const uniqueUrls = new Map<string, string>();
+
+    for (const url of urls) {
+      const key = getUrlKey(url);
+      if (!uniqueUrls.has(key)) {
+        uniqueUrls.set(key, url);
+      }
+    }
+
+    return Array.from(uniqueUrls.entries()).map(([key, url]) => ({
+      key,
+      url,
+      parsed: parseFigmaUrl(url),
+    }));
+  }, [allFigmaUrls, figmaUrl]);
+
+  // Handle iframe load
+  const handleIframeLoad = useCallback((urlKey: string) => {
+    setLoadedUrls(prev => {
+      const next = new Set(prev);
+      next.add(urlKey);
+      return next;
+    });
+  }, []);
+
+  // Calculate zoom transform
+  const zoomStyle: React.CSSProperties = zoom !== 100
+    ? {
+        transform: `scale(${zoom / 100})`,
+        transformOrigin: "center",
+        width: `${100 / (zoom / 100)}%`,
+        height: `${100 / (zoom / 100)}%`,
+      }
+    : {};
+
+  // Check if current URL is loaded
+  const isCurrentLoaded = loadedUrls.has(currentKey);
+
+  // If we can't parse the URL, show error
+  if (!currentParsed) {
+    return (
+      <div className={className} style={{ ...style, display: "flex", alignItems: "center", justifyContent: "center" }}>
+        <div className="flex flex-col items-center gap-2 text-tertiary p-4 text-center">
+          <FigmaIcon className="w-6 h-6" />
+          <span className="text-xs">Unable to embed Figma design</span>
+          <button
+            onClick={() => window.open(figmaUrl, "_blank", "noopener,noreferrer")}
+            className="text-xs text-[--color-accent] hover:underline"
+          >
+            Open in Figma
+          </button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} style={{ ...style, position: "relative", overflow: "hidden" }}>
+      {/* Loading overlay - shows while current iframe is loading */}
+      {!isCurrentLoaded && (
+        <div className="absolute inset-0 flex items-center justify-center bg-[--bg-secondary] z-20">
+          <div className="flex flex-col items-center gap-2">
+            <FigmaIcon className="w-5 h-5 text-tertiary animate-pulse" />
+            <span className="text-xs text-tertiary">Loading Figma...</span>
+          </div>
+        </div>
+      )}
+
+      {/* Error overlay */}
+      {error && (
+        <div className="absolute inset-0 flex items-center justify-center bg-[--bg-secondary] z-20">
+          <div className="flex flex-col items-center gap-2 text-tertiary">
+            <FigmaIcon className="w-6 h-6" />
+            <span className="text-xs">{error}</span>
+          </div>
+        </div>
+      )}
+
+      {/*
+        Iframe pool: Pre-load all variant URLs as hidden iframes.
+        Only the current variant's iframe is visible (opacity: 1, z-index: 10).
+        Others are hidden (opacity: 0, z-index: 1) but stay loaded.
+
+        This approach works because:
+        1. Figma iframes stay active even when hidden
+        2. Switching just changes CSS visibility
+        3. No network requests when switching variants
+      */}
+      {urlsToPreload.map(({ key, parsed }) => {
+        if (!parsed) return null;
+
+        const embedUrl = buildEmbedUrl(parsed.fileKey, parsed.nodeId);
+        const isActive = key === currentKey;
+        const isLoaded = loadedUrls.has(key);
+
+        return (
+          <iframe
+            key={key}
+            src={embedUrl}
+            className="absolute inset-0 w-full h-full border-0 transition-opacity duration-150"
+            style={{
+              ...zoomStyle,
+              opacity: isActive && isLoaded ? 1 : 0,
+              zIndex: isActive ? 10 : 1,
+              pointerEvents: isActive ? "auto" : "none",
+            }}
+            onLoad={() => handleIframeLoad(key)}
+            onError={() => setError("Failed to load Figma embed")}
+            allowFullScreen
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * Hook to collect all Figma URLs from a segment's variants.
+ * This enables the FigmaEmbed to preload all variant iframes.
+ */
+export function useAllFigmaUrls(
+  segment: { meta: { figma?: string }; variants?: Array<{ figma?: string }> } | undefined
+): string[] {
+  return useMemo(() => {
+    if (!segment) return [];
+
+    const urls: string[] = [];
+
+    // Add meta-level Figma URL
+    if (segment.meta.figma) {
+      urls.push(segment.meta.figma);
+    }
+
+    // Add variant-level Figma URLs
+    if (segment.variants) {
+      for (const variant of segment.variants) {
+        if (variant.figma) {
+          urls.push(variant.figma);
+        }
+      }
+    }
+
+    // Deduplicate
+    return [...new Set(urls)];
+  }, [segment]);
+}