@fragments-sdk/cli 0.2.2

package/src/viewer/components/PreviewArea.tsx

@@ -0,0 +1,404 @@
+/**
+ * PreviewArea component - handles rendering the component preview.
+ * Extracted from App.tsx for better organization and performance.
+ *
+ * Now supports iframe-based isolation for CSS isolation between
+ * the viewer shell and user's component library.
+ */
+
+import { memo, type ReactNode } from 'react';
+import type { SegmentVariant } from '../../core/index.js';
+import { ErrorBoundary } from './ErrorBoundary.js';
+import { FigmaEmbed } from './FigmaEmbed.js';
+import { VariantMatrix } from './VariantMatrix.js';
+import { MultiViewportPreview } from './MultiViewportPreview.js';
+import { IsolatedPreviewFrame } from './IsolatedPreviewFrame.js';
+import { getBackgroundStyle, type ZoomLevel, type BackgroundOption } from './PreviewToolbar.js';
+import type { PreviewTheme } from '../hooks/useViewSettings.js';
+import { getViewportWidth, type ViewportPreset, type ViewportSize } from './ViewportSelector.js';
+
+interface PreviewAreaProps {
+  // Component data
+  componentName: string;
+  segmentPath: string;
+  variant: SegmentVariant | undefined;
+  variants: SegmentVariant[] | undefined;
+
+  // View settings
+  zoom: ZoomLevel;
+  background: BackgroundOption;
+  viewport: ViewportPreset;
+  customSize: ViewportSize;
+  previewTheme: PreviewTheme;
+
+  // Display modes
+  showMatrixView: boolean;
+  showMultiViewport: boolean;
+  showComparison: boolean;
+
+  // Figma
+  figmaUrl?: string;
+  allFigmaUrls: string[];
+
+  // Callbacks
+  onSelectVariant: (index: number) => void;
+  onRetry: () => void;
+
+  // Render function for variant content (used as fallback and for matrix/multi-viewport)
+  renderContent: () => ReactNode;
+
+  // Keys for forcing re-renders
+  previewKey: string;
+
+  // Whether to use iframe isolation (default: true)
+  useIframeIsolation?: boolean;
+}
+
+// Device mockup component for tablet/mobile preview
+interface DeviceMockupProps {
+  type: 'tablet' | 'mobile';
+  width: number;
+  children: React.ReactNode;
+}
+
+const DeviceMockup = memo(function DeviceMockup({ type, width, children }: DeviceMockupProps) {
+  const isMobile = type === 'mobile';
+  const frameWidth = width + 24;
+  const frameHeight = isMobile ? 720 : 1024;
+  const screenHeight = frameHeight - (isMobile ? 80 : 48);
+
+  return (
+    <div className="relative flex-shrink-0" style={{ width: `${frameWidth}px` }}>
+      <div
+        className="relative rounded-[40px] bg-[#1a1a1a] p-3 shadow-2xl"
+        style={{
+          boxShadow: '0 25px 50px -12px rgba(0, 0, 0, 0.5), inset 0 1px 0 rgba(255,255,255,0.1)',
+        }}
+      >
+        {isMobile && (
+          <>
+            <div className="absolute -left-[3px] top-24 w-[3px] h-8 bg-[#2a2a2a] rounded-l" />
+            <div className="absolute -left-[3px] top-36 w-[3px] h-12 bg-[#2a2a2a] rounded-l" />
+            <div className="absolute -left-[3px] top-52 w-[3px] h-12 bg-[#2a2a2a] rounded-l" />
+            <div className="absolute -right-[3px] top-32 w-[3px] h-16 bg-[#2a2a2a] rounded-r" />
+          </>
+        )}
+
+        <div
+          className="relative rounded-[32px] overflow-hidden bg-white"
+          style={{ height: `${screenHeight}px` }}
+        >
+          {isMobile ? (
+            <div className="absolute top-0 left-1/2 -translate-x-1/2 w-[120px] h-[30px] bg-[#1a1a1a] rounded-b-2xl z-10 flex items-center justify-center gap-2">
+              <div className="w-2 h-2 rounded-full bg-[#2a2a2a]" />
+              <div className="w-12 h-1.5 rounded-full bg-[#2a2a2a]" />
+            </div>
+          ) : (
+            <div className="absolute top-2 left-1/2 -translate-x-1/2 w-3 h-3 rounded-full bg-[#2a2a2a] z-10" />
+          )}
+
+          <div className="w-full h-full overflow-auto">{children}</div>
+
+          <div className="absolute bottom-2 left-1/2 -translate-x-1/2 w-[100px] h-1 bg-black/20 rounded-full z-10" />
+        </div>
+      </div>
+    </div>
+  );
+});
+
+// Inner preview content with zoom transform
+interface PreviewContentProps {
+  zoom: ZoomLevel;
+  previewTheme: PreviewTheme;
+  background: BackgroundOption;
+  children: ReactNode;
+}
+
+const PreviewContent = memo(function PreviewContent({ zoom, previewTheme, background, children }: PreviewContentProps) {
+  return (
+    <div
+      data-preview-container="true"
+      data-theme={previewTheme}
+      className="w-full h-full overflow-auto"
+      style={{
+        backgroundColor: background === 'transparent' ? 'transparent' : undefined,
+      }}
+    >
+      <div
+        className="p-6"
+        style={{
+          transform: `scale(${zoom / 100})`,
+          transformOrigin: 'top left',
+          width: zoom !== 100 ? `${100 / (zoom / 100)}%` : '100%',
+          color: '#1f2937',
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+});
+
+export function PreviewArea({
+  componentName,
+  segmentPath,
+  variant,
+  variants,
+  zoom,
+  background,
+  viewport,
+  customSize,
+  previewTheme,
+  showMatrixView,
+  showMultiViewport,
+  showComparison,
+  figmaUrl,
+  allFigmaUrls,
+  onSelectVariant,
+  onRetry,
+  renderContent,
+  previewKey,
+  useIframeIsolation = true,
+}: PreviewAreaProps) {
+  // Matrix view
+  if (showMatrixView && variants) {
+    return (
+      <VariantMatrix
+        variants={variants}
+        componentName={componentName}
+        segmentPath={segmentPath}
+        zoom={zoom}
+        previewTheme={previewTheme}
+        background={background}
+        useIframeIsolation={useIframeIsolation}
+        onSelectVariant={(index) => {
+          onSelectVariant(index);
+        }}
+      />
+    );
+  }
+
+  // Multi-viewport view
+  if (showMultiViewport && variant) {
+    return (
+      <MultiViewportPreview
+        componentName={componentName}
+        segmentPath={segmentPath}
+        variantName={variant.name}
+        renderContent={renderContent}
+        previewTheme={previewTheme}
+        background={background}
+        zoom={zoom}
+        useIframeIsolation={useIframeIsolation}
+      />
+    );
+  }
+
+  const viewportWidth = getViewportWidth(viewport, customSize);
+  const viewportHeight = viewport === 'custom' ? customSize.height : null;
+  const isDevice = viewport === 'tablet' || viewport === 'mobile';
+  const backgroundStyle = getBackgroundStyle(background);
+
+  // Device mockup view (tablet/mobile)
+  if (isDevice && viewportWidth && variant) {
+    const deviceScreenHeight = viewport === 'mobile' ? 640 : 976;
+
+    if (showComparison && figmaUrl) {
+      return (
+        <div className="min-h-full flex flex-col p-6">
+          <div className="flex gap-4 flex-1">
+            <div className="flex-1 flex flex-col">
+              <div className="text-xs font-medium text-tertiary mb-2 text-center">Rendered</div>
+              <div className="flex-1 flex items-center justify-center" style={backgroundStyle}>
+                <DeviceMockup type={viewport as 'tablet' | 'mobile'} width={viewportWidth}>
+                  {useIframeIsolation ? (
+                    <IsolatedPreviewFrame
+                      segmentPath={segmentPath}
+                      variantName={variant.name}
+                      theme={previewTheme}
+                      width={viewportWidth}
+                      height={deviceScreenHeight}
+                      previewKey={previewKey}
+                    />
+                  ) : (
+                    <PreviewContent zoom={zoom} previewTheme={previewTheme} background={background}>
+                      <ErrorBoundary key={previewKey} componentName={componentName} onRetry={onRetry}>
+                        {renderContent()}
+                      </ErrorBoundary>
+                    </PreviewContent>
+                  )}
+                </DeviceMockup>
+              </div>
+            </div>
+
+            <div className="flex-1 flex flex-col">
+              <div className="text-xs font-medium text-tertiary mb-2 text-center">Figma Design</div>
+              <FigmaEmbed
+                figmaUrl={figmaUrl}
+                allFigmaUrls={allFigmaUrls}
+                zoom={zoom}
+                className="flex-1 rounded-lg border border-[--border] overflow-hidden"
+                style={backgroundStyle}
+              />
+            </div>
+          </div>
+        </div>
+      );
+    }
+
+    return (
+      <div className="min-h-full flex items-center justify-center p-8">
+        <DeviceMockup type={viewport as 'tablet' | 'mobile'} width={viewportWidth}>
+          {useIframeIsolation ? (
+            <IsolatedPreviewFrame
+              segmentPath={segmentPath}
+              variantName={variant.name}
+              theme={previewTheme}
+              width={viewportWidth}
+              height={deviceScreenHeight}
+              previewKey={previewKey}
+            />
+          ) : (
+            <PreviewContent zoom={zoom} previewTheme={previewTheme} background={background}>
+              <ErrorBoundary key={previewKey} componentName={componentName} onRetry={onRetry}>
+                {renderContent()}
+              </ErrorBoundary>
+            </PreviewContent>
+          )}
+        </DeviceMockup>
+      </div>
+    );
+  }
+
+  // Side-by-side comparison view
+  if (showComparison && figmaUrl && variant) {
+    return (
+      <div className="min-h-full flex flex-col p-6">
+        <div className="flex gap-4 flex-1">
+          <div className="flex-1 flex flex-col">
+            <div className="text-xs font-medium text-tertiary mb-2 text-center">Rendered</div>
+            <div
+              className="flex-1 rounded-lg border border-[--border] overflow-auto"
+              style={backgroundStyle}
+            >
+              {useIframeIsolation ? (
+                <IsolatedPreviewFrame
+                  segmentPath={segmentPath}
+                  variantName={variant.name}
+                  theme={previewTheme}
+                  width="100%"
+                  height="100%"
+                  minHeight={300}
+                  previewKey={previewKey}
+                />
+              ) : (
+                <div
+                  className="flex items-center justify-center p-8"
+                  data-preview-container="true"
+                  data-theme={previewTheme}
+                >
+                  <div
+                    style={{
+                      transform: `scale(${zoom / 100})`,
+                      transformOrigin: 'top left',
+                      width: zoom !== 100 ? `${100 / (zoom / 100)}%` : '100%',
+                      color: '#1f2937',
+                    }}
+                  >
+                    <ErrorBoundary key={previewKey} componentName={componentName} onRetry={onRetry}>
+                      {renderContent()}
+                    </ErrorBoundary>
+                  </div>
+                </div>
+              )}
+            </div>
+          </div>
+
+          <div className="flex-1 flex flex-col">
+            <div className="text-xs font-medium text-tertiary mb-2 text-center">Figma Design</div>
+            <FigmaEmbed
+              figmaUrl={figmaUrl}
+              allFigmaUrls={allFigmaUrls}
+              zoom={zoom}
+              className="flex-1 rounded-lg border border-[--border] overflow-hidden"
+              style={backgroundStyle}
+            />
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // Regular preview (responsive or desktop)
+  // Use iframe isolation when enabled for complete CSS isolation
+  if (useIframeIsolation && variant) {
+    // When no specific viewport width, fill the container
+    const isFullWidth = !viewportWidth;
+
+    return (
+      <div className={isFullWidth ? "h-full flex flex-col" : "min-h-full flex items-center justify-center p-6"}>
+        <div
+          className="relative transition-all duration-200"
+          style={{
+            width: viewportWidth ? `${viewportWidth}px` : '100%',
+            maxWidth: viewportWidth ? undefined : '100%',
+            height: isFullWidth ? '100%' : undefined,
+            minHeight: viewportHeight ? `${viewportHeight}px` : (isFullWidth ? undefined : '200px'),
+            ...(viewportWidth && {
+              backgroundColor: 'var(--bg-primary)',
+              borderRadius: '8px',
+              boxShadow: '0 0 0 1px var(--border), 0 4px 12px rgba(0,0,0,0.15)',
+            }),
+          }}
+        >
+          <IsolatedPreviewFrame
+            segmentPath={segmentPath}
+            variantName={variant.name}
+            theme={previewTheme}
+            width="100%"
+            height="100%"
+            minHeight={viewportHeight || 200}
+            previewKey={previewKey}
+          />
+        </div>
+      </div>
+    );
+  }
+
+  // Fallback: Direct rendering without iframe isolation
+  return (
+    <div className="min-h-full flex items-center justify-center p-6">
+      <div
+        className="relative transition-all duration-200"
+        data-preview-container="true"
+        data-theme={previewTheme}
+        style={{
+          width: viewportWidth ? `${viewportWidth}px` : '100%',
+          maxWidth: viewportWidth ? undefined : '100%',
+          minHeight: viewportHeight ? `${viewportHeight}px` : '100%',
+          ...(viewportWidth && {
+            backgroundColor: 'var(--bg-primary)',
+            borderRadius: '8px',
+            boxShadow: '0 0 0 1px var(--border), 0 4px 12px rgba(0,0,0,0.15)',
+          }),
+        }}
+      >
+        <div
+          className="p-8"
+          style={{
+            transform: `scale(${zoom / 100})`,
+            transformOrigin: 'top left',
+            width: zoom !== 100 ? `${100 / (zoom / 100)}%` : '100%',
+            color: '#1f2937',
+          }}
+        >
+          <ErrorBoundary key={previewKey} componentName={componentName} onRetry={onRetry}>
+            {renderContent()}
+          </ErrorBoundary>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export { DeviceMockup };

package/src/viewer/components/PreviewFrameHost.tsx

@@ -0,0 +1,310 @@
+/**
+ * PreviewFrameHost - Iframe-side component that renders components in isolation
+ *
+ * This component runs inside the preview iframe and:
+ * 1. Listens for render requests from the parent window
+ * 2. Loads and renders the requested segment variant
+ * 3. Applies theme styling
+ * 4. Reports render status back to parent
+ */
+
+import { useState, useEffect, useRef, type ReactNode } from 'react';
+import { useFrameBridge } from '../hooks/usePreviewBridge.js';
+
+// Types for segment data
+interface SegmentVariant {
+  name: string;
+  render: (options?: { loadedData?: Record<string, unknown> }) => ReactNode;
+  loaders?: Array<() => Promise<Record<string, unknown>>>;
+  props?: Record<string, unknown>;
+  hasPlayFunction?: boolean;
+}
+
+interface SegmentDefinition {
+  meta: {
+    name: string;
+    description?: string;
+  };
+  variants?: SegmentVariant[];
+}
+
+interface SegmentItem {
+  path: string;
+  segment: SegmentDefinition;
+}
+
+// Cached segments
+let cachedSegments: SegmentItem[] | null = null;
+let segmentsPromise: Promise<SegmentItem[]> | null = null;
+
+/**
+ * Load segments from the virtual module
+ */
+async function loadSegments(): Promise<SegmentItem[]> {
+  if (cachedSegments) {
+    return cachedSegments;
+  }
+
+  if (segmentsPromise) {
+    return segmentsPromise;
+  }
+
+  segmentsPromise = (async () => {
+    try {
+      // @ts-expect-error Virtual module
+      const module = await import('virtual:fragments');
+      if (module.segmentsPromise) {
+        cachedSegments = await module.segmentsPromise;
+      } else {
+        cachedSegments = module.segments || [];
+      }
+      return cachedSegments!;
+    } catch (error) {
+      console.error('[PreviewFrameHost] Failed to load segments:', error);
+      throw error;
+    }
+  })();
+
+  return segmentsPromise;
+}
+
+/**
+ * Find a segment by its path
+ */
+function findSegmentByPath(segments: SegmentItem[], path: string): SegmentItem | undefined {
+  return segments.find(s => s.path === path);
+}
+
+/**
+ * Find a variant by name within a segment
+ */
+function findVariant(segment: SegmentDefinition, variantName: string): SegmentVariant | undefined {
+  return segment.variants?.find(v => v.name === variantName);
+}
+
+/**
+ * Error boundary for catching render errors
+ */
+function ErrorDisplay({ message, stack }: { message: string; stack?: string }) {
+  return (
+    <div className="preview-error">
+      <div style={{ fontWeight: 500, marginBottom: 8 }}>Render Error</div>
+      <div>{message}</div>
+      {stack && (
+        <pre style={{ marginTop: 8, fontSize: 11, opacity: 0.8 }}>
+          {stack}
+        </pre>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Loading indicator
+ */
+function LoadingIndicator() {
+  return (
+    <div className="preview-loading">
+      <div className="spinner" />
+      <span>Loading component...</span>
+    </div>
+  );
+}
+
+/**
+ * Variant renderer that handles async loaders
+ */
+function VariantRenderer({
+  variant,
+  props,
+  onRendered,
+  onError,
+}: {
+  variant: SegmentVariant;
+  props?: Record<string, unknown>;
+  onRendered: (width: number, height: number) => void;
+  onError: (message: string, stack?: string) => void;
+}) {
+  const [content, setContent] = useState<ReactNode | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<{ message: string; stack?: string } | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const hasReported = useRef(false);
+
+  useEffect(() => {
+    hasReported.current = false;
+    setContent(null);
+    setError(null);
+
+    const hasLoaders = variant.loaders && variant.loaders.length > 0;
+
+    if (!hasLoaders) {
+      // No loaders - render immediately
+      try {
+        const rendered = variant.render({ loadedData: props });
+        setContent(rendered);
+      } catch (err) {
+        const errorObj = err instanceof Error ? err : new Error(String(err));
+        setError({ message: errorObj.message, stack: errorObj.stack });
+        onError(errorObj.message, errorObj.stack);
+      }
+      return;
+    }
+
+    // Has loaders - execute them first
+    setIsLoading(true);
+    let cancelled = false;
+
+    async function executeLoaders() {
+      try {
+        const results = await Promise.all(variant.loaders!.map(loader => loader()));
+        if (cancelled) return;
+
+        const merged = results.reduce((acc, result) => ({ ...acc, ...result }), {});
+        const rendered = variant.render({ loadedData: { ...merged, ...props } });
+
+        setContent(rendered);
+        setIsLoading(false);
+      } catch (err) {
+        if (cancelled) return;
+        const errorObj = err instanceof Error ? err : new Error(String(err));
+        setError({ message: errorObj.message, stack: errorObj.stack });
+        setIsLoading(false);
+        onError(errorObj.message, errorObj.stack);
+      }
+    }
+
+    executeLoaders();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [variant, props, onError]);
+
+  // Report rendered size after content renders
+  useEffect(() => {
+    if (!content || hasReported.current) return;
+
+    // Wait for next frame to ensure DOM has updated
+    requestAnimationFrame(() => {
+      if (containerRef.current && !hasReported.current) {
+        const rect = containerRef.current.getBoundingClientRect();
+        hasReported.current = true;
+        onRendered(rect.width, rect.height);
+      }
+    });
+  }, [content, onRendered]);
+
+  if (isLoading) {
+    return <LoadingIndicator />;
+  }
+
+  if (error) {
+    return <ErrorDisplay message={error.message} stack={error.stack} />;
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className="transition-opacity duration-150"
+      style={{
+        display: 'inline-block',
+        opacity: content ? 1 : 0,
+      }}
+    >
+      {content}
+    </div>
+  );
+}
+
+/**
+ * Main PreviewFrameHost component
+ */
+export function PreviewFrameHost() {
+  const { renderRequest, theme, notifyReady, notifyRendered, notifyError } = useFrameBridge();
+  const [segments, setSegments] = useState<SegmentItem[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [currentVariant, setCurrentVariant] = useState<SegmentVariant | null>(null);
+  const [currentProps, setCurrentProps] = useState<Record<string, unknown> | undefined>(undefined);
+
+  // Apply theme to document
+  useEffect(() => {
+    if (theme === 'dark') {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }, [theme]);
+
+  // Load segments on mount
+  useEffect(() => {
+    loadSegments()
+      .then(segs => {
+        setSegments(segs);
+        notifyReady();
+      })
+      .catch(err => {
+        const message = err instanceof Error ? err.message : 'Failed to load segments';
+        setLoadError(message);
+        notifyError(message);
+      });
+  }, [notifyReady, notifyError]);
+
+  // Handle render requests
+  useEffect(() => {
+    if (!renderRequest || !segments) return;
+
+    const { segmentPath, variantName, props } = renderRequest;
+
+    // Find segment
+    const segmentItem = findSegmentByPath(segments, segmentPath);
+    if (!segmentItem) {
+      notifyError(`Segment not found: ${segmentPath}`);
+      setCurrentVariant(null);
+      return;
+    }
+
+    // Find variant
+    const variant = findVariant(segmentItem.segment, variantName);
+    if (!variant) {
+      notifyError(`Variant not found: ${variantName} in ${segmentPath}`);
+      setCurrentVariant(null);
+      return;
+    }
+
+    setCurrentVariant(variant);
+    setCurrentProps(props);
+  }, [renderRequest, segments, notifyError]);
+
+  // Show loading state
+  if (!segments && !loadError) {
+    return <LoadingIndicator />;
+  }
+
+  // Show load error
+  if (loadError) {
+    return <ErrorDisplay message={loadError} />;
+  }
+
+  // Show waiting state
+  if (!currentVariant) {
+    return (
+      <div className="preview-loading">
+        <span>Waiting for render request...</span>
+      </div>
+    );
+  }
+
+  // Render the variant
+  return (
+    <VariantRenderer
+      key={`${renderRequest?.segmentPath}-${renderRequest?.variantName}`}
+      variant={currentVariant}
+      props={currentProps}
+      onRendered={notifyRendered}
+      onError={notifyError}
+    />
+  );
+}
+
+export default PreviewFrameHost;