@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/viewer/components/ContractPanel.tsx

@@ -1,241 +0,0 @@
-/**
- * ContractPanel component - displays FragmentContract metadata for AI agents.
- * Shows propsSummary, scenarioTags, bans, and a11yRules.
- */
-
-import { memo } from 'react';
-import type { FragmentContract } from '../../core/index.js';
-import { Stack, Text, Card, Chip, Alert, EmptyState, CodeBlock, Badge, Box } from '@fragments-sdk/ui';
-
-interface ContractPanelProps {
-  contract?: FragmentContract;
-  componentName: string;
-}
-
-export const ContractPanel = memo(function ContractPanel({
-  contract,
-  componentName,
-}: ContractPanelProps) {
-  // Empty state when no contract metadata
-  if (!contract || isContractEmpty(contract)) {
-    return (
-      <EmptyState>
-        <EmptyState.Icon>
-          <svg
-            style={{ width: '48px', height: '48px', opacity: 0.5 }}
-            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>
-        </EmptyState.Icon>
-        <EmptyState.Title>No contract metadata</EmptyState.Title>
-        <EmptyState.Description>
-          Add a <Box as="code" padding="xs" background="secondary" rounded="sm">contract</Box> field to the fragment definition to enable AI agent features.
-        </EmptyState.Description>
-        <EmptyState.Actions>
-          <CodeBlock
-            code={`contract: {
-  propsSummary: ['variant: primary|secondary'],
-  scenarioTags: ['form.submit', 'action.primary'],
-  a11yRules: ['A11Y_BTN_LABEL'],
-}`}
-            language="typescript"
-            compact
-          />
-        </EmptyState.Actions>
-      </EmptyState>
-    );
-  }
-
-  return (
-    <Box padding="md" style={{ fontSize: '14px' }}>
-      <Stack gap="lg">
-        {/* Props Summary */}
-        {contract.propsSummary && contract.propsSummary.length > 0 && (
-          <Section title="Props Summary">
-            <Card>
-              <Card.Body>
-                <table style={{ width: '100%', fontSize: '12px', borderCollapse: 'collapse' }}>
-                  <thead>
-                    <tr style={{ borderBottom: '1px solid var(--border)' }}>
-                      <th style={{ textAlign: 'left', padding: '8px 16px 8px 0', fontWeight: 500, color: 'var(--text-tertiary)' }}>Name</th>
-                      <th style={{ textAlign: 'left', padding: '8px 16px 8px 0', fontWeight: 500, color: 'var(--text-tertiary)' }}>Type</th>
-                      <th style={{ textAlign: 'left', padding: '8px 0', fontWeight: 500, color: 'var(--text-tertiary)' }}>Description</th>
-                    </tr>
-                  </thead>
-                  <tbody>
-                    {contract.propsSummary.map((prop, i) => {
-                      const parsed = parsePropSummary(prop);
-                      return (
-                        <tr key={i} style={{ borderBottom: i < contract.propsSummary!.length - 1 ? '1px solid var(--border)' : undefined }}>
-                          <td style={{ padding: '8px 16px 8px 0', verticalAlign: 'top' }}>
-                            <Text font="mono" size="xs" weight="medium">{parsed.name}</Text>
-                          </td>
-                          <td style={{ padding: '8px 16px 8px 0', verticalAlign: 'top' }}>
-                            <Badge size="sm">{parsed.type}</Badge>
-                          </td>
-                          <td style={{ padding: '8px 0', verticalAlign: 'top' }}>
-                            <Text size="xs" color="secondary">{parsed.description}</Text>
-                          </td>
-                        </tr>
-                      );
-                    })}
-                  </tbody>
-                </table>
-              </Card.Body>
-            </Card>
-          </Section>
-        )}
-
-        {/* Scenario Tags */}
-        {contract.scenarioTags && contract.scenarioTags.length > 0 && (
-          <Section title="Scenario Tags" subtitle="Used by fragments_suggest for AI queries">
-            <Stack direction="row" gap="sm" style={{ flexWrap: 'wrap' }}>
-              {contract.scenarioTags.map((tag, i) => (
-                <Chip key={i}>{tag}</Chip>
-              ))}
-            </Stack>
-          </Section>
-        )}
-
-        {/* Accessibility Rules */}
-        {contract.a11yRules && contract.a11yRules.length > 0 && (
-          <Section title="Accessibility Rules">
-            <Stack gap="sm">
-              {contract.a11yRules.map((rule, i) => (
-                <Box key={i} padding="sm" background="secondary" rounded="sm">
-                <Stack
-                  direction="row"
-                  align="center"
-                  gap="sm"
-                >
-                  <span style={{ color: '#22c55e' }}>
-                    <svg style={{ width: '16px', height: '16px' }} 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>
-                  <Text font="mono" size="xs" color="secondary">{rule}</Text>
-                </Stack>
-                </Box>
-              ))}
-            </Stack>
-          </Section>
-        )}
-
-        {/* Bans */}
-        {contract.bans && contract.bans.length > 0 && (
-          <Section title="Usage Bans" subtitle="Patterns to avoid">
-            <Stack gap="sm">
-              {contract.bans.map((ban, i) => (
-                <Alert key={i} severity="warning">
-                  <Alert.Body>
-                    <Alert.Title>
-                      <Text font="mono" size="xs">{ban.pattern}</Text>
-                    </Alert.Title>
-                    <Alert.Content>
-                      <Text size="xs" color="tertiary">{ban.message}</Text>
-                    </Alert.Content>
-                  </Alert.Body>
-                </Alert>
-              ))}
-            </Stack>
-          </Section>
-        )}
-
-        {/* Empty sections message */}
-        {isPartialContract(contract) && (
-          <Alert severity="info">
-            <Alert.Body>
-              <Alert.Content>
-                Tip: Add more contract fields to help AI agents better understand this component.
-              </Alert.Content>
-            </Alert.Body>
-          </Alert>
-        )}
-      </Stack>
-    </Box>
-  );
-});
-
-// Helper component for consistent section styling
-interface SectionProps {
-  title: string;
-  subtitle?: string;
-  children: React.ReactNode;
-}
-
-function Section({ title, subtitle, children }: SectionProps) {
-  return (
-    <div>
-      <Stack direction="row" align="center" gap="sm" style={{ marginBottom: '8px' }}>
-        <Text as="h3" size="xs" weight="semibold">{title}</Text>
-        {subtitle && (
-          <Text size="xs" color="tertiary">({subtitle})</Text>
-        )}
-      </Stack>
-      {children}
-    </div>
-  );
-}
-
-// Check if contract is empty or has no meaningful content
-function isContractEmpty(contract: FragmentContract): 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: FragmentContract): 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/EmptyVariantMessage.tsx

@@ -1,54 +0,0 @@
-import { Stack, Text, Alert } from "@fragments-sdk/ui";
-
-interface EmptyVariantMessageProps {
-  reason: string;
-  variantName: string;
-  hint?: string;
-}
-
-export function EmptyVariantMessage({ reason, variantName, hint }: EmptyVariantMessageProps) {
-  return (
-    <Alert variant="warning">
-      <Alert.Body>
-        <Alert.Title>Variant "{variantName}" rendered empty</Alert.Title>
-        <Alert.Content>
-          <Stack direction="column" gap="sm">
-            <Text size="xs" color="secondary">
-              {reason}
-            </Text>
-            {hint && (
-              <Text size="xs" color="tertiary">
-                <Text as="span" size="xs" weight="semibold">
-                  Tip:
-                </Text>{" "}
-                {hint}
-              </Text>
-            )}
-            <div>
-              <Text size="xs" color="tertiary" weight="semibold">
-                Common causes:
-              </Text>
-              <ul style={{ marginTop: "4px", marginLeft: "16px", listStyleType: "disc" }}>
-                <li>
-                  <Text size="xs" color="secondary">
-                    Component requires props that weren't provided
-                  </Text>
-                </li>
-                <li>
-                  <Text size="xs" color="secondary">
-                    Component renders conditionally and conditions aren't met
-                  </Text>
-                </li>
-                <li>
-                  <Text size="xs" color="secondary">
-                    Story args reference variables that don't exist in this context
-                  </Text>
-                </li>
-              </ul>
-            </div>
-          </Stack>
-        </Alert.Content>
-      </Alert.Body>
-    </Alert>
-  );
-}

package/src/viewer/components/ErrorBoundary.tsx

@@ -1,97 +0,0 @@
-import { Component, type ReactNode, type ErrorInfo } from 'react';
-import { Button, Alert, CodeBlock, Collapsible, Stack, Text } from '@fragments-sdk/ui';
-import { ErrorIcon, RefreshIcon } from './Icons.js';
-
-interface ErrorBoundaryProps {
-  children: ReactNode;
-  componentName?: string;
-  fallback?: ReactNode;
-  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) {
-    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) {
-      if (this.props.fallback) {
-        return this.props.fallback;
-      }
-
-      const { componentName } = this.props;
-      const { error, errorInfo } = this.state;
-
-      return (
-        <Alert variant="error">
-          <Alert.Icon>
-            <ErrorIcon style={{ width: '24px', height: '24px' }} />
-          </Alert.Icon>
-          <Alert.Body>
-            <Alert.Title>
-              {componentName ? `Error rendering ${componentName}` : 'Component Error'}
-            </Alert.Title>
-            <Alert.Content>
-              <Stack direction="column" gap="sm">
-                {error && (
-                  <Text size="sm" font="mono" style={{ color: '#dc2626' }}>
-                    {error.message}
-                  </Text>
-                )}
-
-                {errorInfo?.componentStack && (
-                  <Collapsible>
-                    <Collapsible.Trigger>
-                      <Text size="xs" color="tertiary" style={{ cursor: 'pointer' }}>
-                        Show stack trace
-                      </Text>
-                    </Collapsible.Trigger>
-                    <Collapsible.Content>
-                      <div style={{ marginTop: '8px' }}>
-                        <CodeBlock language="plaintext">
-                          {error?.stack || errorInfo.componentStack}
-                        </CodeBlock>
-                      </div>
-                    </Collapsible.Content>
-                  </Collapsible>
-                )}
-
-                <div>
-                  <Button variant="danger" size="sm" onClick={this.handleRetry}>
-                    <RefreshIcon style={{ width: '14px', height: '14px' }} />
-                    Retry
-                  </Button>
-                </div>
-              </Stack>
-            </Alert.Content>
-          </Alert.Body>
-        </Alert>
-      );
-    }
-
-    return this.props.children;
-  }
-}

package/src/viewer/components/FigmaEmbed.tsx

@@ -1,238 +0,0 @@
-import { useRef, useEffect, useState, useMemo, useCallback } from "react";
-import { FigmaIcon } from "./Icons.js";
-import { Stack, Text, Button } from '@fragments-sdk/ui';
-
-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=fragments`;
-
-  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 (
-      <Stack className={className} align="center" justify="center" style={style}>
-        <Stack direction="column" align="center" gap="sm" style={{ color: 'var(--text-tertiary)', padding: '16px', textAlign: 'center' }}>
-          <FigmaIcon style={{ width: '24px', height: '24px' }} />
-          <Text size="xs">Unable to embed Figma design</Text>
-          <Button
-            variant="ghost"
-            size="sm"
-            onClick={() => window.open(figmaUrl, "_blank", "noopener,noreferrer")}
-          >
-            Open in Figma
-          </Button>
-        </Stack>
-      </Stack>
-    );
-  }
-
-  return (
-    <div className={className} style={{ ...style, position: "relative", overflow: "hidden" }}>
-      {/* Loading overlay - shows while current iframe is loading */}
-      {!isCurrentLoaded && (
-        <Stack align="center" justify="center" style={{ position: 'absolute', inset: 0, backgroundColor: 'var(--bg-secondary)', zIndex: 20 }}>
-          <Stack direction="column" align="center" gap="sm">
-            <FigmaIcon style={{ width: '20px', height: '20px', color: 'var(--text-tertiary)' }} />
-            <Text size="xs" color="tertiary">Loading Figma...</Text>
-          </Stack>
-        </Stack>
-      )}
-
-      {/* Error overlay */}
-      {error && (
-        <Stack align="center" justify="center" style={{ position: 'absolute', inset: 0, backgroundColor: 'var(--bg-secondary)', zIndex: 20 }}>
-          <Stack direction="column" align="center" gap="sm" style={{ color: 'var(--text-tertiary)' }}>
-            <FigmaIcon style={{ width: '24px', height: '24px' }} />
-            <Text size="xs">{error}</Text>
-          </Stack>
-        </Stack>
-      )}
-
-      {/*
-        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}
-            style={{
-              position: 'absolute',
-              inset: 0,
-              width: '100%',
-              height: '100%',
-              border: 'none',
-              transition: 'opacity 150ms',
-              ...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 fragment's variants.
- * This enables the FigmaEmbed to preload all variant iframes.
- */
-export function useAllFigmaUrls(
-  fragment: { meta: { figma?: string }; variants?: Array<{ figma?: string }> } | undefined
-): string[] {
-  return useMemo(() => {
-    if (!fragment) return [];
-
-    const urls: string[] = [];
-
-    // Add meta-level Figma URL
-    if (fragment.meta.figma) {
-      urls.push(fragment.meta.figma);
-    }
-
-    // Add variant-level Figma URLs
-    if (fragment.variants) {
-      for (const variant of fragment.variants) {
-        if (variant.figma) {
-          urls.push(variant.figma);
-        }
-      }
-    }
-
-    // Deduplicate
-    return [...new Set(urls)];
-  }, [fragment]);
-}