@fragments-sdk/cli 0.2.2

package/src/viewer/components/IsolatedPreviewFrame.tsx

@@ -0,0 +1,321 @@
+/**
+ * IsolatedPreviewFrame - Parent-side iframe wrapper for CSS isolation
+ *
+ * Renders component previews inside an iframe for complete CSS isolation.
+ * This prevents CSS conflicts between:
+ * - The viewer shell and the user's component library
+ * - Global styles from user components
+ * - Theme variables with same names
+ */
+
+import { memo, useRef, useEffect, useState, useCallback } from 'react';
+import clsx from 'clsx';
+import { usePreviewBridge, type ParentMessage } from '../hooks/usePreviewBridge.js';
+
+/** Maximum number of retry attempts */
+const MAX_RETRIES = 3;
+
+export interface IsolatedPreviewFrameProps {
+  /** Segment path (file path) to render */
+  segmentPath: string;
+  /** Variant name to render */
+  variantName: string;
+  /** Props to pass to the variant render function */
+  props?: Record<string, unknown>;
+  /** Theme for the preview */
+  theme: 'light' | 'dark';
+  /** Width of the preview (CSS value) */
+  width?: number | string;
+  /** Height of the preview (CSS value) */
+  height?: number | string;
+  /** Minimum height of the preview */
+  minHeight?: number | string;
+  /** Background style for the preview container */
+  background?: React.CSSProperties;
+  /** Additional class name for the container */
+  className?: string;
+  /** Additional styles for the container */
+  style?: React.CSSProperties;
+  /** Called when content size is reported */
+  onContentSize?: (size: { width: number; height: number }) => void;
+  /** Called when an error occurs */
+  onError?: (error: string) => void;
+  /** Unique key to force re-render on variant changes */
+  previewKey?: string;
+  /** Show size indicator on hover */
+  showSizeIndicator?: boolean;
+}
+
+/**
+ * IsolatedPreviewFrame renders a component preview inside an iframe
+ * for complete CSS isolation from the viewer shell.
+ */
+export const IsolatedPreviewFrame = memo(function IsolatedPreviewFrame({
+  segmentPath,
+  variantName,
+  props,
+  theme,
+  width = '100%',
+  height = 'auto',
+  minHeight = 120,
+  background,
+  className = '',
+  style,
+  onContentSize,
+  onError,
+  previewKey,
+  showSizeIndicator = false,
+}: IsolatedPreviewFrameProps) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [frameError, setFrameError] = useState<string | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+  const [iframeKey, setIframeKey] = useState(0);
+  const { isReady, isRendering, lastError, contentSize, render, setTheme, clearError } = usePreviewBridge(iframeRef);
+  const lastRenderRef = useRef<string>('');
+  const isFirstLoad = useRef(true);
+
+  // Build the preview URL
+  const previewUrl = '/fragments/preview/';
+
+  // Handle iframe load
+  const handleLoad = useCallback(() => {
+    setIsLoading(false);
+    setFrameError(null);
+    isFirstLoad.current = false;
+  }, []);
+
+  // Handle iframe error
+  const handleError = useCallback(() => {
+    setIsLoading(false);
+    setFrameError('Failed to load preview frame');
+    onError?.('Failed to load preview frame');
+  }, [onError]);
+
+  // Handle retry
+  const handleRetry = useCallback(() => {
+    if (retryCount >= MAX_RETRIES) return;
+
+    setFrameError(null);
+    clearError();
+    setRetryCount(c => c + 1);
+    setIsLoading(true);
+    lastRenderRef.current = ''; // Force re-render
+    setIframeKey(k => k + 1); // Force iframe reload
+  }, [retryCount, clearError]);
+
+  // Send render request when ready or when render params change
+  useEffect(() => {
+    if (!isReady) return;
+
+    // Create a render key to detect changes
+    const renderKey = `${segmentPath}:${variantName}:${JSON.stringify(props)}:${previewKey || ''}`;
+    if (renderKey === lastRenderRef.current) return;
+    lastRenderRef.current = renderKey;
+
+    render(segmentPath, variantName, props);
+  }, [isReady, segmentPath, variantName, props, previewKey, render]);
+
+  // Sync theme when it changes
+  useEffect(() => {
+    if (!isReady) return;
+    setTheme(theme);
+  }, [isReady, theme, setTheme]);
+
+  // Report content size changes
+  useEffect(() => {
+    if (contentSize) {
+      onContentSize?.(contentSize);
+    }
+  }, [contentSize, onContentSize]);
+
+  // Report errors
+  useEffect(() => {
+    if (lastError) {
+      setFrameError(lastError);
+      onError?.(lastError);
+    }
+  }, [lastError, onError]);
+
+  // Calculate iframe dimensions
+  const frameWidth = typeof width === 'number' ? `${width}px` : width;
+  const frameHeight = typeof height === 'number' ? `${height}px` : height;
+  const frameMinHeight = typeof minHeight === 'number' ? `${minHeight}px` : minHeight;
+
+  // Determine if we should show skeleton vs spinner
+  // Skeleton for initial load, spinner for subsequent renders
+  const showSkeleton = isLoading && isFirstLoad.current;
+  const showSpinner = !showSkeleton && (isLoading || isRendering);
+  const showContent = isReady && !isRendering && !frameError;
+
+  return (
+    <div
+      className={clsx('isolated-preview-frame group', className)}
+      style={{
+        position: 'relative',
+        width: frameWidth,
+        height: frameHeight,
+        minHeight: frameMinHeight,
+        ...background,
+        ...style,
+      }}
+    >
+      {/* Skeleton loading overlay (initial load) */}
+      <div
+        className={clsx(
+          'absolute inset-0 z-10 transition-opacity duration-150',
+          showSkeleton ? 'opacity-100' : 'opacity-0 pointer-events-none'
+        )}
+        style={{ background: 'rgba(255, 255, 255, 0.95)' }}
+      >
+        <PreviewSkeleton />
+      </div>
+
+      {/* Spinner overlay (subsequent renders) */}
+      <div
+        className={clsx(
+          'absolute inset-0 z-10 flex items-center justify-center transition-opacity duration-150',
+          showSpinner ? 'opacity-100' : 'opacity-0 pointer-events-none'
+        )}
+        style={{ background: 'rgba(255, 255, 255, 0.8)' }}
+      >
+        <div style={{ display: 'flex', alignItems: 'center', gap: 8, color: '#6b7280', fontSize: 14 }}>
+          <LoadingSpinner />
+          <span>Rendering...</span>
+        </div>
+      </div>
+
+      {/* Error overlay */}
+      <div
+        className={clsx(
+          'absolute inset-0 z-10 flex items-center justify-center p-4 transition-opacity duration-150',
+          frameError && !isLoading ? 'opacity-100' : 'opacity-0 pointer-events-none'
+        )}
+        style={{ background: 'rgba(254, 242, 242, 0.95)' }}
+      >
+        <div
+          style={{
+            background: 'white',
+            border: '1px solid #fecaca',
+            borderRadius: 8,
+            padding: 16,
+            maxWidth: 400,
+          }}
+        >
+          <div style={{ color: '#dc2626', fontWeight: 500, marginBottom: 8 }}>
+            Preview Error
+          </div>
+          <div style={{ color: '#991b1b', fontSize: 13, marginBottom: retryCount < MAX_RETRIES ? 12 : 0 }}>
+            {frameError}
+          </div>
+          {retryCount < MAX_RETRIES && (
+            <button
+              onClick={handleRetry}
+              style={{
+                padding: '6px 12px',
+                fontSize: 13,
+                fontWeight: 500,
+                color: 'white',
+                background: '#dc2626',
+                border: 'none',
+                borderRadius: 6,
+                cursor: 'pointer',
+              }}
+            >
+              Retry ({MAX_RETRIES - retryCount} remaining)
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* The iframe */}
+      <iframe
+        key={iframeKey}
+        ref={iframeRef}
+        src={previewUrl}
+        title={`Preview: ${variantName}`}
+        onLoad={handleLoad}
+        onError={handleError}
+        className={clsx(
+          'transition-opacity duration-150',
+          showContent ? 'opacity-100' : 'opacity-0'
+        )}
+        style={{
+          width: '100%',
+          height: '100%',
+          border: 'none',
+          display: 'block',
+          background: 'transparent',
+        }}
+        // Security attributes
+        sandbox="allow-scripts allow-same-origin"
+      />
+
+      {/* Size indicator */}
+      {showSizeIndicator && contentSize && (
+        <div
+          className="absolute bottom-1 right-1 px-1.5 py-0.5 rounded font-mono
+                     opacity-0 group-hover:opacity-100 transition-opacity duration-150"
+          style={{
+            background: 'rgba(0, 0, 0, 0.5)',
+            color: 'white',
+            fontSize: 10,
+          }}
+        >
+          {contentSize.width} × {contentSize.height}px
+        </div>
+      )}
+    </div>
+  );
+});
+
+/**
+ * Skeleton loading placeholder
+ */
+function PreviewSkeleton() {
+  return (
+    <div className="animate-pulse p-4">
+      <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-1/3 mb-3" />
+      <div className="h-8 bg-gray-200 dark:bg-gray-700 rounded mb-2" />
+      <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-2/3" />
+    </div>
+  );
+}
+
+/**
+ * Simple loading spinner component
+ */
+function LoadingSpinner() {
+  return (
+    <svg
+      style={{
+        width: 20,
+        height: 20,
+        animation: 'spin 0.8s linear infinite',
+      }}
+      viewBox="0 0 24 24"
+      fill="none"
+    >
+      <style>
+        {`@keyframes spin { to { transform: rotate(360deg); } }`}
+      </style>
+      <circle
+        cx="12"
+        cy="12"
+        r="10"
+        stroke="#e5e7eb"
+        strokeWidth="2"
+        fill="none"
+      />
+      <path
+        d="M12 2a10 10 0 0 1 10 10"
+        stroke="#3b82f6"
+        strokeWidth="2"
+        strokeLinecap="round"
+        fill="none"
+      />
+    </svg>
+  );
+}
+
+export default IsolatedPreviewFrame;

package/src/viewer/components/IsolatedRender.tsx

@@ -0,0 +1,111 @@
+import { useMemo, useEffect, useState } from "react";
+import type { SegmentDefinition } from "../../core/index.js";
+import { VariantRenderer } from "./VariantRenderer.js";
+import { getBackgroundStyle, type BackgroundOption, type ZoomLevel } from "./PreviewToolbar.js";
+
+interface IsolatedRenderProps {
+  segments: Array<{ path: string; segment: SegmentDefinition }>;
+}
+
+/**
+ * Isolated render component for screenshot capture and standalone viewing.
+ * Renders a single variant with minimal UI for visual testing.
+ * URL params: ?isolated=true&component=Name&variant=VariantName&zoom=100&bg=white&theme=light
+ */
+export function IsolatedRender({ segments }: IsolatedRenderProps) {
+  const [ready, setReady] = useState(false);
+
+  // Parse query parameters
+  const params = useMemo(() => {
+    const searchParams = new URLSearchParams(window.location.search);
+    const zoomParam = parseInt(searchParams.get("zoom") || "100", 10);
+    const bgParam = searchParams.get("bg") || "white";
+    return {
+      component: searchParams.get("component"),
+      variant: searchParams.get("variant"),
+      theme: searchParams.get("theme") || "light",
+      zoom: [50, 75, 100, 150, 200].includes(zoomParam) ? zoomParam as ZoomLevel : 100 as ZoomLevel,
+      background: ["white", "black", "checkerboard", "transparent"].includes(bgParam)
+        ? bgParam as BackgroundOption
+        : "white" as BackgroundOption,
+    };
+  }, []);
+
+  // Find the matching segment and variant
+  const match = useMemo(() => {
+    if (!params.component || !params.variant) {
+      return null;
+    }
+
+    const segment = segments.find(
+      (s) => s.segment.meta.name === params.component
+    );
+
+    if (!segment) {
+      return null;
+    }
+
+    const variant = segment.segment.variants.find(
+      (v) => v.name === params.variant
+    );
+
+    if (!variant) {
+      return null;
+    }
+
+    return { segment: segment.segment, variant };
+  }, [segments, params]);
+
+  // Apply theme
+  useEffect(() => {
+    document.documentElement.setAttribute("data-theme", params.theme);
+    
+    // Signal ready after a short delay for fonts and styles to settle
+    const timer = setTimeout(() => {
+      setReady(true);
+    }, 50);
+
+    return () => clearTimeout(timer);
+  }, [params.theme]);
+
+  // Error state - missing component or variant
+  if (!params.component || !params.variant) {
+    return (
+      <div className="p-4 text-red-500 font-mono text-sm">
+        Error: Missing component or variant parameter
+        <pre className="mt-2 text-xs">
+          Required: ?component=ComponentName&variant=VariantName
+        </pre>
+      </div>
+    );
+  }
+
+  // Error state - component/variant not found
+  if (!match) {
+    return (
+      <div className="p-4 text-red-500 font-mono text-sm">
+        Error: Component "{params.component}" variant "{params.variant}" not
+        found
+      </div>
+    );
+  }
+
+  // Render the variant in isolation
+  return (
+    <div
+      id="isolated-render"
+      data-ready={ready}
+      className="min-h-screen p-8 flex items-center justify-center"
+      style={getBackgroundStyle(params.background)}
+    >
+      <div
+        style={{
+          transform: `scale(${params.zoom / 100})`,
+          transformOrigin: 'center center',
+        }}
+      >
+        <VariantRenderer variant={match.variant} />
+      </div>
+    </div>
+  );
+}

package/src/viewer/components/KeyboardShortcutsHelp.tsx

@@ -0,0 +1,89 @@
+/**
+ * Keyboard Shortcuts Help Modal
+ *
+ * Displays all available keyboard shortcuts in a modal overlay.
+ */
+
+import { useEffect } from "react";
+import { SHORTCUTS } from "../hooks/useKeyboardShortcuts.js";
+import { CloseIcon } from "./Icons.js";
+
+interface KeyboardShortcutsHelpProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export function KeyboardShortcutsHelp({ isOpen, onClose }: KeyboardShortcutsHelpProps) {
+  // Close on escape
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        onClose();
+      }
+    };
+
+    document.addEventListener("keydown", handleEscape);
+    return () => document.removeEventListener("keydown", handleEscape);
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center p-4"
+      onClick={onClose}
+    >
+      {/* Backdrop */}
+      <div className="absolute inset-0 bg-black/50 backdrop-blur-sm" />
+
+      {/* Modal */}
+      <div
+        className="relative bg-[--bg-primary] border border-[--border] rounded-xl shadow-2xl max-w-md w-full"
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-4 border-b border-[--border]">
+          <h2 className="text-base font-semibold text-primary">Keyboard Shortcuts</h2>
+          <button
+            onClick={onClose}
+            className="p-1.5 text-tertiary hover:text-primary hover:bg-[--bg-hover] rounded-lg transition-colors"
+          >
+            <CloseIcon className="w-4 h-4" />
+          </button>
+        </div>
+
+        {/* Shortcuts List */}
+        <div className="p-5 space-y-3">
+          {SHORTCUTS.map((shortcut, index) => (
+            <div key={index} className="flex items-center justify-between">
+              <span className="text-sm text-secondary">{shortcut.description}</span>
+              <div className="flex items-center gap-1.5">
+                {shortcut.keys.map((key, keyIndex) => (
+                  <span key={keyIndex} className="flex items-center">
+                    {keyIndex > 0 && (
+                      <span className="text-xs text-tertiary mx-1">or</span>
+                    )}
+                    <kbd className="px-2 py-1 text-xs font-mono bg-[--bg-secondary] border border-[--border] rounded text-primary">
+                      {key}
+                    </kbd>
+                  </span>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+
+        {/* Footer */}
+        <div className="px-5 py-3 border-t border-[--border] bg-[--bg-secondary] rounded-b-xl">
+          <p className="text-xs text-tertiary text-center">
+            Press <kbd className="px-1.5 py-0.5 text-xs font-mono bg-[--bg-primary] border border-[--border] rounded">?</kbd> to toggle this help
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default KeyboardShortcutsHelp;