@fragments-sdk/viewer 0.2.1

package/src/components/PreviewFrameHost.tsx

@@ -0,0 +1,304 @@
+/**
+ * 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 fragment variant
+ * 3. Applies theme styling
+ * 4. Reports render status back to parent
+ */
+
+import { useState, useEffect, useRef } from 'react';
+import {
+  usePreviewVariantRuntime,
+  type FragmentVariant,
+} from '@fragments-sdk/core';
+import { useFrameBridge } from '../hooks/usePreviewBridge.js';
+
+// Types for fragment data
+interface PreviewFragmentDefinition {
+  meta: {
+    name: string;
+    description?: string;
+    category?: string;
+  };
+  variants?: FragmentVariant[];
+}
+
+interface FragmentItem {
+  path: string;
+  fragment: PreviewFragmentDefinition;
+}
+
+// Cached fragments
+let cachedFragments: FragmentItem[] | null = null;
+let fragmentsPromise: Promise<FragmentItem[]> | null = null;
+
+/**
+ * Load fragments from the virtual module
+ */
+async function loadFragments(): Promise<FragmentItem[]> {
+  if (cachedFragments) {
+    return cachedFragments;
+  }
+
+  if (fragmentsPromise) {
+    return fragmentsPromise;
+  }
+
+  fragmentsPromise = (async () => {
+    try {
+      // @ts-expect-error Virtual module
+      const module = await import('virtual:fragments');
+      if (module.fragmentsPromise) {
+        cachedFragments = await module.fragmentsPromise;
+      } else {
+        cachedFragments = module.fragments || [];
+      }
+      return cachedFragments!;
+    } catch (error) {
+      console.error('[PreviewFrameHost] Failed to load fragments:', error);
+      throw error;
+    }
+  })();
+
+  return fragmentsPromise;
+}
+
+/**
+ * Find a fragment by its path
+ */
+function findFragmentByPath(fragments: FragmentItem[], path: string): FragmentItem | undefined {
+  return fragments.find(s => s.path === path);
+}
+
+/**
+ * Find a variant by name within a fragment
+ */
+function findVariant(fragment: PreviewFragmentDefinition, variantName: string): FragmentVariant | undefined {
+  return fragment.variants?.find(v => v.name === variantName);
+}
+
+type PreviewMode = 'centered' | 'full-bleed';
+
+function resolvePreviewMode(fragment: PreviewFragmentDefinition): PreviewMode {
+  const name = fragment.meta.name.toLowerCase();
+  const category = (fragment.meta.category || '').toLowerCase();
+
+  if (name.includes('appshell') || name.includes('sidebar') || name.includes('header') || name.includes('layout')) {
+    return 'full-bleed';
+  }
+
+  return 'centered';
+}
+
+/**
+ * Error boundary for catching render errors
+ */
+function ErrorDisplay({ message, stack }: { message: string; stack?: string }) {
+  return (
+    <div style={{ padding: '16px', color: '#dc2626', background: 'rgba(254, 242, 242, 0.95)', borderRadius: '8px', margin: '16px' }}>
+      <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 style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '32px', gap: '8px', color: '#6b7280' }}>
+      <div style={{ width: '16px', height: '16px', border: '2px solid #e5e7eb', borderTopColor: '#3b82f6', borderRadius: '50%', animation: 'spin 0.8s linear infinite' }} />
+      <style>{`@keyframes spin { to { transform: rotate(360deg); } }`}</style>
+      <span>Loading component...</span>
+    </div>
+  );
+}
+
+/**
+ * Variant renderer that handles async loaders
+ */
+function VariantRenderer({
+  variant,
+  props,
+  mode,
+  onRendered,
+  onError,
+}: {
+  variant: FragmentVariant;
+  props?: Record<string, unknown>;
+  mode: PreviewMode;
+  onRendered: (width: number, height: number) => void;
+  onError: (message: string, stack?: string) => void;
+}) {
+  const { content, isLoading, error } = usePreviewVariantRuntime({
+    variant,
+    loadedData: props,
+  });
+  const containerRef = useRef<HTMLDivElement>(null);
+  const hasReported = useRef(false);
+  const lastReportedError = useRef<string | null>(null);
+
+  useEffect(() => {
+    hasReported.current = false;
+  }, [variant, props, mode]);
+
+  useEffect(() => {
+    if (!error) {
+      lastReportedError.current = null;
+      return;
+    }
+
+    const signature = `${error.message}:${error.stack ?? ''}`;
+    if (lastReportedError.current === signature) {
+      return;
+    }
+
+    lastReportedError.current = signature;
+    onError(error.message, error.stack);
+  }, [error, onError]);
+
+  // Report rendered size after content renders
+  useEffect(() => {
+    if (!content || hasReported.current || isLoading || error) 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, error, isLoading, onRendered]);
+
+  if (isLoading) {
+    return <LoadingIndicator />;
+  }
+
+  if (error) {
+    return <ErrorDisplay message={error.message} stack={error.stack} />;
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      style={{
+        display: 'block',
+        width: mode === 'full-bleed' ? '100%' : 'fit-content',
+        maxWidth: '100%',
+        minHeight: mode === 'full-bleed' ? '100%' : undefined,
+        transition: 'opacity 150ms',
+        opacity: content ? 1 : 0,
+      }}
+    >
+      {content}
+    </div>
+  );
+}
+
+/**
+ * Main PreviewFrameHost component
+ */
+export function PreviewFrameHost() {
+  const { renderRequest, theme, notifyReady, notifyRendered, notifyError } = useFrameBridge();
+  const [fragments, setFragments] = useState<FragmentItem[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [currentVariant, setCurrentVariant] = useState<FragmentVariant | null>(null);
+  const [currentProps, setCurrentProps] = useState<Record<string, unknown> | undefined>(undefined);
+  const [previewMode, setPreviewMode] = useState<PreviewMode>('centered');
+
+  // Apply theme to document
+  useEffect(() => {
+    if (theme === 'dark') {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }, [theme]);
+
+  useEffect(() => {
+    document.body.setAttribute('data-preview-mode', previewMode);
+  }, [previewMode]);
+
+  // Load fragments on mount
+  useEffect(() => {
+    loadFragments()
+      .then(segs => {
+        setFragments(segs);
+        notifyReady();
+      })
+      .catch(err => {
+        const message = err instanceof Error ? err.message : 'Failed to load fragments';
+        setLoadError(message);
+        notifyError(message);
+      });
+  }, [notifyReady, notifyError]);
+
+  // Handle render requests
+  useEffect(() => {
+    if (!renderRequest || !fragments) return;
+
+    const { fragmentPath, variantName, props } = renderRequest;
+
+    // Find fragment
+    const fragmentItem = findFragmentByPath(fragments, fragmentPath);
+    if (!fragmentItem) {
+      notifyError(`Fragment not found: ${fragmentPath}`);
+      setCurrentVariant(null);
+      return;
+    }
+
+    // Find variant
+    const variant = findVariant(fragmentItem.fragment, variantName);
+    if (!variant) {
+      notifyError(`Variant not found: ${variantName} in ${fragmentPath}`);
+      setCurrentVariant(null);
+      return;
+    }
+
+    setPreviewMode(resolvePreviewMode(fragmentItem.fragment));
+    setCurrentVariant(variant);
+    setCurrentProps(props);
+  }, [renderRequest, fragments, notifyError]);
+
+  // Show loading state
+  if (!fragments && !loadError) {
+    return <LoadingIndicator />;
+  }
+
+  // Show load error
+  if (loadError) {
+    return <ErrorDisplay message={loadError} />;
+  }
+
+  // Show waiting state
+  if (!currentVariant) {
+    return (
+      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', padding: '32px', gap: '8px', color: '#6b7280' }}>
+        <span>Waiting for render request...</span>
+      </div>
+    );
+  }
+
+  // Render the variant
+  return (
+    <VariantRenderer
+      key={`${renderRequest?.fragmentPath}-${renderRequest?.variantName}`}
+      variant={currentVariant}
+      props={currentProps}
+      mode={previewMode}
+      onRendered={notifyRendered}
+      onError={notifyError}
+    />
+  );
+}
+
+export default PreviewFrameHost;

package/src/components/PreviewToolbar.tsx

@@ -0,0 +1,80 @@
+import { useEffect, useCallback } from 'react';
+import { Button, Menu, Stack } from '@fragments-sdk/ui';
+import { ZOOM_LEVELS, type ZoomLevel } from '../constants/ui.js';
+import { ZoomIcon, ChevronDownIcon } from './Icons.js';
+
+// Re-export types for consumers
+export type { ZoomLevel };
+
+interface PreviewToolbarProps {
+  zoom: ZoomLevel;
+  onZoomChange: (zoom: ZoomLevel) => void;
+}
+
+export function PreviewToolbar({
+  zoom,
+  onZoomChange,
+}: PreviewToolbarProps) {
+  // Keyboard shortcuts for zoom
+  const handleKeyDown = useCallback((e: KeyboardEvent) => {
+    // Don't handle if in input/textarea
+    const target = e.target as HTMLElement;
+    if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable) {
+      return;
+    }
+
+    if (e.key === '=' || e.key === '+') {
+      e.preventDefault();
+      const currentIndex = ZOOM_LEVELS.indexOf(zoom);
+      if (currentIndex < ZOOM_LEVELS.length - 1) {
+        onZoomChange(ZOOM_LEVELS[currentIndex + 1]);
+      }
+    } else if (e.key === '-') {
+      e.preventDefault();
+      const currentIndex = ZOOM_LEVELS.indexOf(zoom);
+      if (currentIndex > 0) {
+        onZoomChange(ZOOM_LEVELS[currentIndex - 1]);
+      }
+    } else if (e.key === '0') {
+      e.preventDefault();
+      onZoomChange(100);
+    }
+  }, [zoom, onZoomChange]);
+
+  useEffect(() => {
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [handleKeyDown]);
+
+  return (
+    <Stack direction="row" gap="sm" align="center">
+      <Menu>
+        <Menu.Trigger asChild>
+          <Button variant="ghost" size="sm" title="Zoom level (+/-/0)">
+            <Stack direction="row" gap="xs" align="center">
+              <span style={{ display: 'inline-flex', width: '14px', height: '14px' }}>
+                <ZoomIcon />
+              </span>
+              <span>{zoom}%</span>
+              <span style={{ display: 'inline-flex', width: '12px', height: '12px' }}>
+                <ChevronDownIcon />
+              </span>
+            </Stack>
+          </Button>
+        </Menu.Trigger>
+        <Menu.Content side="bottom" align="start">
+          <Menu.RadioGroup
+            value={String(zoom)}
+            onValueChange={(value: string) => onZoomChange(Number(value) as ZoomLevel)}
+          >
+            {ZOOM_LEVELS.map((level) => (
+              <Menu.RadioItem key={level} value={String(level)}>
+                {level}%
+              </Menu.RadioItem>
+            ))}
+          </Menu.RadioGroup>
+        </Menu.Content>
+      </Menu>
+    </Stack>
+  );
+}