@fragments-sdk/viewer 0.2.1

package/src/components/PreviewArea.tsx

@@ -0,0 +1,254 @@
+/**
+ * PreviewArea - routes to the appropriate preview mode.
+ *
+ * Pure routing component that selects between matrix, multi-viewport,
+ * device mockup, Figma comparison, iframe-isolated, or direct-render views.
+ */
+
+import type { ReactNode } from "react";
+import type { FragmentVariant } from "@fragments-sdk/core";
+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 { ShadowPreview } from "./ShadowPreview.js";
+import { DeviceMockup } from "./DeviceMockup.js";
+import {
+  getViewportWidth,
+  type ZoomLevel,
+  type ViewportPreset,
+  type ViewportSize,
+} from "../constants/ui.js";
+import type { PreviewTheme } from "../hooks/useViewSettings.js";
+
+interface PreviewAreaProps {
+  componentName: string;
+  fragmentPath: string;
+  variant: FragmentVariant | undefined;
+  variants: FragmentVariant[] | undefined;
+  zoom: ZoomLevel;
+  viewport: ViewportPreset;
+  customSize: ViewportSize;
+  previewTheme: PreviewTheme;
+  showMatrixView: boolean;
+  showMultiViewport: boolean;
+  showComparison: boolean;
+  figmaUrl?: string;
+  allFigmaUrls: string[];
+  onSelectVariant: (index: number) => void;
+  onRetry: () => void;
+  renderContent: () => ReactNode;
+  previewKey: string;
+  useIframeIsolation?: boolean;
+}
+
+export function PreviewArea({
+  componentName,
+  fragmentPath,
+  variant,
+  variants,
+  zoom,
+  viewport,
+  customSize,
+  previewTheme,
+  showMatrixView,
+  showMultiViewport,
+  showComparison,
+  figmaUrl,
+  allFigmaUrls,
+  onSelectVariant,
+  onRetry,
+  renderContent,
+  previewKey,
+  useIframeIsolation = false,
+}: PreviewAreaProps) {
+  // Matrix view — all variants in a grid
+  if (showMatrixView && variants) {
+    return (
+      <VariantMatrix
+        variants={variants}
+        componentName={componentName}
+        fragmentPath={fragmentPath}
+        zoom={zoom}
+        previewTheme={previewTheme}
+        useIframeIsolation={useIframeIsolation}
+        onSelectVariant={onSelectVariant}
+      />
+    );
+  }
+
+  // Multi-viewport — mobile/tablet/desktop side by side
+  if (showMultiViewport && variant) {
+    return (
+      <MultiViewportPreview
+        componentName={componentName}
+        fragmentPath={fragmentPath}
+        variantName={variant.name}
+        renderContent={renderContent}
+        previewTheme={previewTheme}
+        zoom={zoom}
+        useIframeIsolation={useIframeIsolation}
+      />
+    );
+  }
+
+  const viewportWidth = getViewportWidth(viewport, customSize);
+  const isDevice = viewport === "tablet" || viewport === "mobile";
+
+  // Render either iframe-isolated or direct fallback content
+  const renderPreview = (width: number | string, height: number | string) => {
+    if (useIframeIsolation && variant) {
+      return (
+        <IsolatedPreviewFrame
+          fragmentPath={fragmentPath}
+          variantName={variant.name}
+          theme={previewTheme}
+          width={width}
+          height={height}
+          previewKey={previewKey}
+        />
+      );
+    }
+    return (
+      <ShadowPreview theme={previewTheme} width={width} height={height}>
+        <ErrorBoundary
+          key={previewKey}
+          componentName={componentName}
+          onRetry={onRetry}
+        >
+          {renderContent()}
+        </ErrorBoundary>
+      </ShadowPreview>
+    );
+  };
+
+  // Device mockup (tablet/mobile with physical chrome)
+  if (isDevice && viewportWidth && variant) {
+    const deviceScreenHeight = viewport === "mobile" ? 640 : 976;
+    const deviceContent = (
+      <DeviceMockup
+        type={viewport as "tablet" | "mobile"}
+        width={viewportWidth}
+      >
+        {renderPreview(viewportWidth, deviceScreenHeight)}
+      </DeviceMockup>
+    );
+
+    if (showComparison && figmaUrl) {
+      return (
+        <ComparisonLayout
+          figmaUrl={figmaUrl}
+          allFigmaUrls={allFigmaUrls}
+          zoom={zoom}
+        >
+          <div
+            style={{
+              flex: 1,
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+            }}
+          >
+            {deviceContent}
+          </div>
+        </ComparisonLayout>
+      );
+    }
+
+    return (
+      <div
+        style={{
+          minHeight: "100%",
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          padding: 32,
+        }}
+      >
+        {deviceContent}
+      </div>
+    );
+  }
+
+  // Side-by-side Figma comparison (non-device)
+  if (showComparison && figmaUrl && variant) {
+    return (
+      <ComparisonLayout
+        figmaUrl={figmaUrl}
+        allFigmaUrls={allFigmaUrls}
+        zoom={zoom}
+      >
+        <div
+          style={{
+            flex: 1,
+            borderRadius: 8,
+            border: "1px solid var(--border)",
+            overflow: "auto",
+          }}
+        >
+          {renderPreview("100%", "100%")}
+        </div>
+      </ComparisonLayout>
+    );
+  }
+
+  // Default: full-size isolated preview or direct render fallback
+  return renderPreview("100%", "100%");
+}
+
+// --- Local helpers ---
+
+const comparisonLabelStyle: React.CSSProperties = {
+  fontSize: 12,
+  fontWeight: 500,
+  color: "var(--text-tertiary)",
+  marginBottom: 8,
+  textAlign: "center",
+};
+
+interface ComparisonLayoutProps {
+  children: ReactNode;
+  figmaUrl: string;
+  allFigmaUrls: string[];
+  zoom: ZoomLevel;
+}
+
+function ComparisonLayout({
+  children,
+  figmaUrl,
+  allFigmaUrls,
+  zoom,
+}: ComparisonLayoutProps) {
+  return (
+    <div
+      style={{
+        minHeight: "100%",
+        display: "flex",
+        flexDirection: "column",
+        padding: 24,
+      }}
+    >
+      <div style={{ display: "flex", gap: 16, flex: 1 }}>
+        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
+          <div style={comparisonLabelStyle}>Rendered</div>
+          {children}
+        </div>
+        <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
+          <div style={comparisonLabelStyle}>Figma Design</div>
+          <FigmaEmbed
+            figmaUrl={figmaUrl}
+            allFigmaUrls={allFigmaUrls}
+            zoom={zoom}
+            style={{
+              flex: 1,
+              borderRadius: 8,
+              border: "1px solid var(--border)",
+              overflow: "hidden",
+            }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/PreviewAside.tsx

@@ -0,0 +1,168 @@
+import { useState, useEffect, useMemo } from "react";
+import type { FragmentDefinition, FragmentVariant } from '@fragments-sdk/core';
+import { Box, Stack, Text, Separator, Button, TableOfContents } from "@fragments-sdk/ui";
+import { getVariantSectionId } from "./viewer-utils.js";
+
+interface TocHeading {
+  id: string;
+  text: string;
+  level: 2 | 3;
+}
+
+interface PreviewAsideProps {
+  fragment: FragmentDefinition;
+  variants: FragmentVariant[];
+  focusedVariantIndex: number;
+  activePanel: string;
+  onSelectVariant: (index: number) => void;
+  onCopyLink: () => void;
+  onShowShortcuts: () => void;
+}
+
+function buildHeadings(fragment: FragmentDefinition): TocHeading[] {
+  const headings: TocHeading[] = [{ id: "setup", text: "Setup", level: 2 }];
+
+  if (fragment.variants.length > 0) {
+    headings.push({ id: "examples", text: "Examples", level: 2 });
+  }
+
+  headings.push({ id: "props", text: "Props", level: 2 });
+  headings.push({ id: "usage-guidelines", text: "Usage Guidelines", level: 2 });
+  headings.push({ id: "when-to-use", text: "When to use", level: 3 });
+  headings.push({ id: "when-not-to-use", text: "When not to use", level: 3 });
+
+  if ((fragment.usage?.guidelines?.length ?? 0) > 0) {
+    headings.push({ id: "best-practices", text: "Best practices", level: 3 });
+  }
+
+  if ((fragment.relations?.length ?? 0) > 0) {
+    headings.push({ id: "related-components", text: "Related Components", level: 2 });
+  }
+
+  return headings;
+}
+
+function useActiveHeading(ids: string[]): string | null {
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (ids.length === 0) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+          }
+        }
+      },
+      { rootMargin: "-80px 0px -60% 0px", threshold: 0 }
+    );
+
+    for (const id of ids) {
+      const el = document.getElementById(id);
+      if (el) observer.observe(el);
+    }
+
+    return () => observer.disconnect();
+  }, [ids]);
+
+  return activeId;
+}
+
+export function PreviewAside({
+  fragment,
+  variants,
+  focusedVariantIndex,
+  activePanel,
+  onSelectVariant,
+  onCopyLink,
+  onShowShortcuts,
+}: PreviewAsideProps) {
+  const focusedVariant = variants[focusedVariantIndex] || null;
+
+  const headings = useMemo(() => buildHeadings(fragment), [fragment]);
+  const headingIds = useMemo(() => headings.map((h) => h.id), [headings]);
+  const activeId = useActiveHeading(headingIds);
+
+  return (
+    <Box padding="md" style={{ position: "sticky", top: "80px" }}>
+      <Stack gap="md">
+        {/* On This Page — same TOC component as docs site */}
+        <TableOfContents>
+          {headings.map((heading) => (
+            <TableOfContents.Item
+              key={heading.id}
+              id={heading.id}
+              active={activeId === heading.id}
+              indent={heading.level === 3}
+            >
+              {heading.text}
+            </TableOfContents.Item>
+          ))}
+        </TableOfContents>
+
+        {/* Variant list */}
+        {variants.length > 0 && (
+          <>
+            <Separator />
+            <Stack gap="xs">
+              <Text
+                size="xs"
+                color="tertiary"
+                style={{ textTransform: "uppercase", letterSpacing: "0.08em" }}
+              >
+                Variants
+              </Text>
+              {variants.map((variant, index) => {
+                const active = index === focusedVariantIndex;
+                const anchorId = getVariantSectionId(fragment.meta.name, variant.name);
+
+                return (
+                  <Button
+                    key={variant.name}
+                    as="a"
+                    variant={active ? "secondary" : "ghost"}
+                    size="sm"
+                    href={`#${anchorId}`}
+                    onClick={(event: React.MouseEvent) => {
+                      event.preventDefault();
+                      onSelectVariant(index);
+                    }}
+                    style={{ justifyContent: "flex-start" }}
+                  >
+                    {variant.name}
+                  </Button>
+                );
+              })}
+            </Stack>
+          </>
+        )}
+
+        <Separator />
+        <Stack gap="xs">
+          <Text size="sm" weight="medium">
+            {fragment.meta.name}
+          </Text>
+          <Text size="xs" color="secondary">
+            {focusedVariant
+              ? `Variant: ${focusedVariant.name}`
+              : "Select a variant"}
+          </Text>
+          <Text size="xs" color="tertiary">
+            Active panel: {activePanel}
+          </Text>
+        </Stack>
+        <Separator />
+        <Stack gap="xs">
+          <Button variant="ghost" size="sm" onClick={onCopyLink}>
+            Copy Link
+          </Button>
+          <Button variant="ghost" size="sm" onClick={onShowShortcuts}>
+            Keyboard Shortcuts
+          </Button>
+        </Stack>
+      </Stack>
+    </Box>
+  );
+}