@fragments-sdk/viewer 0.2.1

package/src/components/IsolatedPreviewFrame.tsx

@@ -0,0 +1,390 @@
+/**
+ * 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 { Loading } from "@fragments-sdk/ui";
+import { usePreviewBridge, type ParentMessage } from "../hooks/usePreviewBridge.js";
+
+/** Maximum number of retry attempts */
+const MAX_RETRIES = 3;
+
+/**
+ * Module-level load queue — limits concurrent iframe loads so they don't
+ * all compete for the main thread parsing the same heavy preview bundle.
+ * With MAX_CONCURRENT=1, iframes load sequentially: the first preview
+ * appears in ~1-2s instead of all waiting ~5s.
+ */
+const MAX_CONCURRENT_LOADS = 1;
+let activeLoads = 0;
+const pendingLoads: Array<() => void> = [];
+
+function enqueueLoad(start: () => void): () => void {
+  if (activeLoads < MAX_CONCURRENT_LOADS) {
+    activeLoads++;
+    start();
+  } else {
+    pendingLoads.push(start);
+  }
+  // Return a cancel function for cleanup
+  return () => {
+    const idx = pendingLoads.indexOf(start);
+    if (idx !== -1) pendingLoads.splice(idx, 1);
+  };
+}
+
+function dequeueLoad() {
+  activeLoads--;
+  if (pendingLoads.length > 0 && activeLoads < MAX_CONCURRENT_LOADS) {
+    activeLoads++;
+    const next = pendingLoads.shift()!;
+    next();
+  }
+}
+
+export interface IsolatedPreviewFrameProps {
+  /** Fragment path (file path) to render */
+  fragmentPath: 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 (only for fixed-size contexts like device mockups/grids) */
+  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({
+  fragmentPath,
+  variantName,
+  props,
+  theme,
+  width = "100%",
+  height = "auto",
+  minHeight,
+  background,
+  className = "",
+  style,
+  onContentSize,
+  onError,
+  previewKey,
+  showSizeIndicator = false,
+}: IsolatedPreviewFrameProps) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [frameError, setFrameError] = useState<string | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+  const [iframeKey, setIframeKey] = useState(0);
+  const [hasRenderedOnce, setHasRenderedOnce] = useState(false);
+  const [isInView, setIsInView] = useState(false);
+  const [canLoad, setCanLoad] = useState(false);
+  const hasDequeued = useRef(false);
+  const { isReady, isRendering, lastError, contentSize, render, setTheme, clearError } =
+    usePreviewBridge(iframeRef);
+  const lastRenderRef = useRef<string>("");
+  const [isHovered, setIsHovered] = useState(false);
+
+  // Build the preview URL
+  const previewUrl = "/fragments/preview/";
+
+  // Step 1: IntersectionObserver detects when container is near viewport
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setIsInView(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin: "200px" }
+    );
+
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  // Step 2: When in view, enter the load queue — iframe renders when slot opens
+  useEffect(() => {
+    if (!isInView) return;
+    const cancel = enqueueLoad(() => setCanLoad(true));
+    return cancel;
+  }, [isInView]);
+
+  // Handle iframe load — release queue slot so next iframe can start
+  const handleLoad = useCallback(() => {
+    setIsLoading(false);
+    setFrameError(null);
+    if (!hasDequeued.current) {
+      hasDequeued.current = true;
+      dequeueLoad();
+    }
+  }, []);
+
+  // Handle iframe error — also release queue slot
+  const handleError = useCallback(() => {
+    setIsLoading(false);
+    setFrameError("Failed to load preview frame");
+    onError?.("Failed to load preview frame");
+    if (!hasDequeued.current) {
+      hasDequeued.current = true;
+      dequeueLoad();
+    }
+  }, [onError]);
+
+  // Handle retry
+  const handleRetry = useCallback(() => {
+    if (retryCount >= MAX_RETRIES) return;
+
+    setFrameError(null);
+    clearError();
+    setRetryCount((c) => c + 1);
+    setIsLoading(true);
+    setHasRenderedOnce(false);
+    hasDequeued.current = false;
+    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 = `${fragmentPath}:${variantName}:${JSON.stringify(props)}:${previewKey || ""}`;
+    if (renderKey === lastRenderRef.current) return;
+    lastRenderRef.current = renderKey;
+
+    render(fragmentPath, variantName, props);
+  }, [isReady, fragmentPath, 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) {
+      setHasRenderedOnce(true);
+      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 =
+    minHeight != null ? (typeof minHeight === "number" ? `${minHeight}px` : minHeight) : undefined;
+
+  // Keep first-load skeleton visible until the first successful render signal.
+  // After first render, preserve content visibility and show spinner overlays
+  // for later renders to avoid white/blank flashes.
+  const showSkeleton = !hasRenderedOnce && !frameError;
+  const showSpinner = hasRenderedOnce && !frameError && (isLoading || isRendering);
+  const showContent = !frameError && (hasRenderedOnce || (isReady && !isRendering));
+
+  return (
+    <div
+      ref={containerRef}
+      style={{
+        position: "relative",
+        width: frameWidth,
+        height: frameHeight,
+        minHeight: frameMinHeight,
+        ...style,
+      }}
+    >
+      {/* Skeleton loading overlay (initial load, not in view, or queued) */}
+      {(showSkeleton || !canLoad) && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            zIndex: 10,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            background: "var(--bg-primary, rgba(255, 255, 255, 0.95))",
+            padding: 32,
+          }}
+        >
+          <Loading size="md" />
+        </div>
+      )}
+
+      {/* Spinner overlay (subsequent renders) */}
+      {showSpinner && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            zIndex: 10,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            background: "color-mix(in srgb, var(--bg-primary, white) 80%, transparent)",
+          }}
+        >
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: 8,
+              color: "var(--text-tertiary, #6b7280)",
+              fontSize: 14,
+            }}
+          >
+            <Loading size="sm" />
+            <span>Rendering...</span>
+          </div>
+        </div>
+      )}
+
+      {/* Error overlay */}
+      {frameError && !isLoading && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            zIndex: 10,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            padding: "16px",
+            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 — only loads when in view AND queue slot is available */}
+      {canLoad && (
+        <iframe
+          key={iframeKey}
+          ref={iframeRef}
+          src={previewUrl}
+          title={`Preview: ${variantName}`}
+          onLoad={handleLoad}
+          onError={handleError}
+          style={{
+            width: frameWidth,
+            height: frameHeight,
+            minHeight: frameMinHeight,
+            border: "none",
+            display: "block",
+            background: "transparent",
+            transition: "opacity 120ms ease",
+            opacity: showContent ? 1 : 0,
+          }}
+          // Security attributes
+          sandbox="allow-scripts allow-same-origin"
+          className={className}
+          onMouseEnter={() => setIsHovered(true)}
+          onMouseLeave={() => setIsHovered(false)}
+        />
+      )}
+
+      {/* Size indicator */}
+      {showSizeIndicator && contentSize && (
+        <div
+          style={{
+            position: "absolute",
+            bottom: "4px",
+            right: "4px",
+            padding: "2px 6px",
+            borderRadius: "4px",
+            fontFamily: "monospace",
+            opacity: isHovered ? 1 : 0,
+            transition: "opacity 150ms",
+            background: "rgba(0, 0, 0, 0.5)",
+            color: "white",
+            fontSize: 10,
+          }}
+        >
+          {contentSize.width} × {contentSize.height}px
+        </div>
+      )}
+    </div>
+  );
+});
+
+export default IsolatedPreviewFrame;

package/src/components/IsolatedRender.tsx

@@ -0,0 +1,113 @@
+import { useMemo, useEffect, useState } from "react";
+import type { FragmentDefinition } from '@fragments-sdk/core';
+import { VariantRenderer } from "./VariantRenderer.js";
+import { type ZoomLevel } from "../constants/ui.js";
+
+interface IsolatedRenderProps {
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
+}
+
+/**
+ * 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&theme=light
+ */
+export function IsolatedRender({ fragments }: 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);
+    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,
+    };
+  }, []);
+
+  // Find the matching fragment and variant
+  const match = useMemo(() => {
+    if (!params.component || !params.variant) {
+      return null;
+    }
+
+    const fragment = fragments.find(
+      (s) => s.fragment.meta.name === params.component
+    );
+
+    if (!fragment) {
+      return null;
+    }
+
+    const variant = fragment.fragment.variants.find(
+      (v) => v.name === params.variant
+    );
+
+    if (!variant) {
+      return null;
+    }
+
+    return { fragment: fragment.fragment, variant };
+  }, [fragments, 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 style={{ padding: '16px', color: '#ef4444', fontFamily: 'monospace', fontSize: '14px' }}>
+        Error: Missing component or variant parameter
+        <pre style={{ marginTop: '8px', fontSize: '12px' }}>
+          Required: ?component=ComponentName&variant=VariantName
+        </pre>
+      </div>
+    );
+  }
+
+  // Error state - component/variant not found
+  if (!match) {
+    return (
+      <div style={{ padding: '16px', color: '#ef4444', fontFamily: 'monospace', fontSize: '14px' }}>
+        Error: Component "{params.component}" variant "{params.variant}" not
+        found
+      </div>
+    );
+  }
+
+  // Render the variant in isolation
+  return (
+    <div
+      id="isolated-render"
+      data-ready={ready}
+      style={{
+        minHeight: '100vh',
+        padding: '32px',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: 'var(--bg-primary)',
+      }}
+    >
+      <div
+        style={{
+          transform: `scale(${params.zoom / 100})`,
+          transformOrigin: 'center center',
+        }}
+      >
+        <VariantRenderer variant={match.variant} />
+      </div>
+    </div>
+  );
+}

package/src/components/KeyboardShortcutsHelp.tsx

@@ -0,0 +1,53 @@
+/**
+ * Keyboard Shortcuts Help Modal
+ *
+ * Displays all available keyboard shortcuts in a modal overlay.
+ * Uses Fragments UI Dialog compound component.
+ */
+
+import { Dialog, Stack, Text, Badge } from '@fragments-sdk/ui';
+import { SHORTCUTS } from "../hooks/useKeyboardShortcuts.js";
+
+interface KeyboardShortcutsHelpProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export function KeyboardShortcutsHelp({ isOpen, onClose }: KeyboardShortcutsHelpProps) {
+  return (
+    <Dialog open={isOpen} onOpenChange={(open: boolean) => { if (!open) onClose(); }}>
+      <Dialog.Content size="md">
+        <Dialog.Header>
+          <Dialog.Title>Keyboard Shortcuts</Dialog.Title>
+          <Dialog.Close />
+        </Dialog.Header>
+        <Dialog.Body>
+          <Stack direction="column" gap="sm">
+            {SHORTCUTS.map((shortcut, index) => (
+              <Stack key={index} direction="row" align="center" justify="between">
+                <Text size="sm" color="secondary">{shortcut.description}</Text>
+                <Stack direction="row" align="center" gap="xs">
+                  {shortcut.keys.map((key, keyIndex) => (
+                    <span key={keyIndex} style={{ display: 'flex', alignItems: 'center' }}>
+                      {keyIndex > 0 && (
+                        <Text size="xs" color="tertiary" style={{ margin: '0 4px' }}>or</Text>
+                      )}
+                      <Badge variant="default" size="sm">{key}</Badge>
+                    </span>
+                  ))}
+                </Stack>
+              </Stack>
+            ))}
+          </Stack>
+        </Dialog.Body>
+        <Dialog.Footer>
+          <Text size="xs" color="tertiary" style={{ textAlign: 'center', width: '100%' }}>
+            Press <Badge variant="default" size="sm">?</Badge> to toggle this help
+          </Text>
+        </Dialog.Footer>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
+
+export default KeyboardShortcutsHelp;