@fragments-sdk/cli 0.2.2

package/src/viewer/components/App.tsx

@@ -0,0 +1,638 @@
+/**
+ * Main App component for the Fragments viewer.
+ * Refactored for better performance and maintainability.
+ */
+
+import { useState, useMemo, useEffect, useCallback, useRef } from "react";
+import type { SegmentDefinition } from "../../core/index.js";
+import clsx from "clsx";
+
+// Layout & Navigation
+import { Layout } from "./Layout.js";
+import { LeftSidebar } from "./LeftSidebar.js";
+import { VariantTabs } from "./VariantTabs.js";
+import { CommandPalette } from "./CommandPalette.js";
+import { KeyboardShortcutsHelp } from "./KeyboardShortcutsHelp.js";
+import { Toast, type ToastMessage } from "./Toast.js";
+
+// Toolbar
+import { PreviewToolbar, getBackgroundStyle } from "./PreviewToolbar.js";
+import { ViewportSelector } from "./ViewportSelector.js";
+
+// Preview & Rendering
+import { PreviewArea } from "./PreviewArea.js";
+import { BottomPanel } from "./BottomPanel.js";
+import { IsolatedRender } from "./IsolatedRender.js";
+import { StoryRenderer, LoaderIndicator } from "./StoryRenderer.js";
+import { HealthDashboard } from "./HealthDashboard.js";
+import { useAllFigmaUrls } from "./FigmaEmbed.js";
+import { ActionCapture } from "./ActionCapture.js";
+
+// Icons
+import { EmptyIcon, ExternalLinkIcon, CameraIcon, FigmaIcon, CompareIcon, CheckIcon, LinkIcon, GridIcon, DevicesIcon } from "./Icons.js";
+
+// Hooks
+import { useAppState } from "../hooks/useAppState.js";
+import { useViewSettings } from "../hooks/useViewSettings.js";
+import { useFigmaIntegration } from "../hooks/useFigmaIntegration.js";
+import { useKeyboardShortcuts } from "../hooks/useKeyboardShortcuts.js";
+import { useActions } from "../hooks/useActions.js";
+import { useUrlState, findSegmentByName, findVariantIndex } from "../hooks/useUrlState.js";
+import { usePanelDock } from "./ResizablePanel.js";
+import { useTheme } from "./ThemeProvider.js";
+
+// Utilities
+import { ScreenshotButton } from "./ScreenshotButton.js";
+
+interface AppProps {
+  segments: Array<{ path: string; segment: SegmentDefinition }>;
+}
+
+export function App({ segments }: AppProps) {
+  // URL state management
+  const { state: urlState, setComponent: setUrlComponent, setVariant: setUrlVariant, setViewSettings: setUrlViewSettings, copyUrl } = useUrlState();
+
+  // UI state (modals, panels, view modes)
+  const { state: uiState, actions: uiActions } = useAppState();
+
+  // View settings (zoom, background, viewport, theme)
+  const viewSettings = useViewSettings({
+    initialState: {
+      zoom: urlState.zoom as any,
+      background: urlState.background as any,
+      viewport: urlState.viewport as any,
+      customSize: { width: urlState.customWidth, height: urlState.customHeight },
+    },
+    onZoomChange: (zoom) => setUrlViewSettings({ zoom }),
+    onBackgroundChange: (bg) => setUrlViewSettings({ background: bg }),
+    onViewportChange: (vp, size) => setUrlViewSettings({
+      viewport: vp,
+      customWidth: size?.width,
+      customHeight: size?.height,
+    }),
+  });
+
+  // Panel dock position
+  const panelDock = usePanelDock();
+
+  // Get resolved theme from ThemeProvider for iframe preview
+  const { resolvedTheme } = useTheme();
+
+  // Toast notifications
+  const [toasts, setToasts] = useState<ToastMessage[]>([]);
+  const addToast = useCallback((type: ToastMessage['type'], message: string, duration?: number) => {
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    setToasts(prev => [...prev, { id, type, message, duration }]);
+  }, []);
+  const dismissToast = useCallback((id: string) => {
+    setToasts(prev => prev.filter(t => t.id !== id));
+  }, []);
+
+  // Navigation state
+  const [activeSegmentPath, setActiveSegmentPath] = useState<string | null>(() => {
+    if (urlState.component) {
+      const found = findSegmentByName(segments, urlState.component);
+      return found?.path ?? segments[0]?.path ?? null;
+    }
+    return segments[0]?.path ?? null;
+  });
+
+  const [activeVariantIndex, setActiveVariantIndex] = useState<number>(() => {
+    const segment = segments.find(s => s.path === activeSegmentPath);
+    if (urlState.variant && segment?.segment.variants) {
+      return findVariantIndex(segment.segment.variants, urlState.variant);
+    }
+    return 0;
+  });
+
+  // Derived values
+  const activeSegment = useMemo(
+    () => segments.find((s) => s.path === activeSegmentPath),
+    [segments, activeSegmentPath]
+  );
+  const activeVariant = activeSegment?.segment.variants?.[activeVariantIndex];
+  const figmaUrl = activeVariant?.figma || activeSegment?.segment.meta.figma;
+
+  // Figma integration
+  const figmaIntegration = useFigmaIntegration({
+    figmaUrl,
+    showComparison: uiState.showComparison,
+    dependencies: [activeSegmentPath, activeVariantIndex],
+  });
+
+  // Actions logging
+  const { logs: actionLogs, logAction, clearLogs: clearActionLogs } = useActions();
+  const useActionsRef = useRef({ logAction });
+  useActionsRef.current = { logAction };
+
+  // Figma URLs for preloading
+  const allFigmaUrls = useAllFigmaUrls(activeSegment?.segment);
+
+  // Reset action logs on variant change
+  useEffect(() => {
+    clearActionLogs();
+  }, [activeSegmentPath, activeVariantIndex, clearActionLogs]);
+
+  // Extract rendered styles after component renders
+  useEffect(() => {
+    if (uiState.showComparison && activeVariant) {
+      const timer = setTimeout(figmaIntegration.extractRenderedStyles, 100);
+      return () => clearTimeout(timer);
+    }
+  }, [uiState.showComparison, activeVariant, figmaIntegration.extractRenderedStyles, uiState.previewKey]);
+
+  // Sync URL state on browser navigation
+  useEffect(() => {
+    if (urlState.component) {
+      const found = findSegmentByName(segments, urlState.component);
+      if (found && found.path !== activeSegmentPath) {
+        setActiveSegmentPath(found.path);
+        const variantIndex = findVariantIndex(found.segment.variants, urlState.variant);
+        setActiveVariantIndex(variantIndex);
+      }
+    }
+  }, [urlState.component, urlState.variant, segments, activeSegmentPath]);
+
+  // HMR toast notifications
+  useEffect(() => {
+    const hot = (import.meta as any).hot;
+    if (!hot) return;
+
+    const handleUpdate = (data: any) => {
+      if (data?.updates?.length > 0) {
+        const paths = data.updates.map((u: any) => u.path.split('/').pop()).join(', ');
+        addToast('info', `Updated: ${paths}`, 2000);
+      }
+    };
+
+    hot.on('vite:beforeUpdate', handleUpdate);
+    return () => hot.off?.('vite:beforeUpdate', handleUpdate);
+  }, [addToast]);
+
+  // Navigation handlers
+  const handleSelectSegment = useCallback((path: string) => {
+    const segment = segments.find((s) => s.path === path);
+    const componentName = segment?.segment.meta.name || path;
+    const firstVariant = segment?.segment.variants?.[0]?.name;
+
+    setActiveSegmentPath(path);
+    setActiveVariantIndex(0);
+    uiActions.setHealthDashboard(false);
+    setUrlComponent(componentName, firstVariant);
+  }, [segments, setUrlComponent, uiActions]);
+
+  const handleSelectVariant = useCallback((index: number) => {
+    const variantName = activeSegment?.segment.variants?.[index]?.name;
+    setActiveVariantIndex(index);
+    setUrlVariant(variantName || null);
+  }, [activeSegment, setUrlVariant]);
+
+  // Copy link handler
+  const handleCopyLink = useCallback(async () => {
+    const success = await copyUrl();
+    if (success) {
+      uiActions.setLinkCopied(true);
+      addToast('success', 'Link copied to clipboard', 2000);
+      setTimeout(() => uiActions.setLinkCopied(false), 2000);
+    }
+  }, [copyUrl, addToast, uiActions]);
+
+  // Sorted segment paths for keyboard navigation
+  const sortedSegmentPaths = useMemo(() => {
+    return [...segments]
+      .filter(s => s.segment?.meta?.name)
+      .sort((a, b) => a.segment.meta.name.localeCompare(b.segment.meta.name))
+      .map(s => s.path);
+  }, [segments]);
+
+  const currentSegmentIndex = sortedSegmentPaths.indexOf(activeSegmentPath || '');
+  const variantCount = activeSegment?.segment.variants?.length || 0;
+
+  // Keyboard shortcuts
+  useKeyboardShortcuts(
+    {
+      nextComponent: () => {
+        const nextIndex = currentSegmentIndex < sortedSegmentPaths.length - 1 ? currentSegmentIndex + 1 : 0;
+        handleSelectSegment(sortedSegmentPaths[nextIndex]);
+      },
+      prevComponent: () => {
+        const prevIndex = currentSegmentIndex > 0 ? currentSegmentIndex - 1 : sortedSegmentPaths.length - 1;
+        handleSelectSegment(sortedSegmentPaths[prevIndex]);
+      },
+      nextVariant: () => handleSelectVariant(activeVariantIndex < variantCount - 1 ? activeVariantIndex + 1 : 0),
+      prevVariant: () => handleSelectVariant(activeVariantIndex > 0 ? activeVariantIndex - 1 : variantCount - 1),
+      goToVariant: (index) => index < variantCount && handleSelectVariant(index),
+      toggleTheme: viewSettings.toggleTheme,
+      togglePanel: uiActions.togglePanel,
+      copyLink: handleCopyLink,
+      showHelp: uiActions.toggleShortcutsHelp,
+      openSearch: () => uiActions.setCommandPalette(true),
+      escape: uiActions.closeAllModals,
+    },
+    { enabled: !uiState.showShortcutsHelp, variantCount }
+  );
+
+  // Render variant with action logging via DOM event capture
+  const renderVariantWithProps = useCallback(() => {
+    if (!activeVariant) return null;
+
+    return (
+      <ActionCapture onAction={useActionsRef.current.logAction}>
+        <StoryRenderer variant={activeVariant}>
+          {(content, isLoading, error) => {
+            if (isLoading) return <div className="flex items-center justify-center p-8"><LoaderIndicator /></div>;
+            if (error) return <EmptyVariantMessage reason={`Error: ${error.message}`} variantName={activeVariant.name} hint="Check the console for the full error stack trace." />;
+            if (content === null || content === undefined) return <EmptyVariantMessage reason="render() returned null or undefined" variantName={activeVariant.name} hint="The variant's render function didn't return any JSX." />;
+            return content;
+          }}
+        </StoryRenderer>
+      </ActionCapture>
+    );
+  }, [activeVariant]);
+
+  // Check if isolated mode
+  const isIsolated = useMemo(() => {
+    const params = new URLSearchParams(window.location.search);
+    return params.get("isolated") === "true";
+  }, []);
+
+  if (isIsolated) {
+    return <IsolatedRender segments={segments} />;
+  }
+
+  return (
+    <>
+      <Toast messages={toasts} onDismiss={dismissToast} />
+      <KeyboardShortcutsHelp isOpen={uiState.showShortcutsHelp} onClose={() => uiActions.setShortcutsHelp(false)} />
+      <CommandPalette
+        isOpen={uiState.showCommandPalette}
+        onClose={() => uiActions.setCommandPalette(false)}
+        segments={segments}
+        onSelectComponent={handleSelectSegment}
+        onSelectVariant={(path, variantIndex) => {
+          handleSelectSegment(path);
+          setTimeout(() => handleSelectVariant(variantIndex), 0);
+        }}
+      />
+
+      <Layout
+        leftSidebar={
+          <LeftSidebar
+            segments={segments}
+            activeSegment={uiState.showHealthDashboard ? null : activeSegmentPath}
+            onSelect={handleSelectSegment}
+            showHealth={uiState.showHealthDashboard}
+            onHealthClick={() => {
+              uiActions.setHealthDashboard(true);
+              setActiveSegmentPath(null);
+            }}
+          />
+        }
+      >
+        {uiState.showHealthDashboard ? (
+          <div className="h-full overflow-auto bg-[--bg-primary]">
+            <div className="max-w-4xl mx-auto py-8 px-6">
+              <HealthDashboard
+                segments={segments}
+                onNavigate={(componentName) => {
+                  const target = segments.find(s => s.segment.meta.name === componentName);
+                  if (target) {
+                    uiActions.setHealthDashboard(false);
+                    handleSelectSegment(target.path);
+                  }
+                }}
+              />
+            </div>
+          </div>
+        ) : activeSegment ? (
+          <div className={clsx("flex h-full", panelDock === "bottom" ? "flex-col" : "flex-row")}>
+            {/* Main Content Area */}
+            <div className="flex-1 flex flex-col min-w-0 min-h-0">
+              {/* Top Toolbar */}
+              <TopToolbar
+                segment={activeSegment}
+                variant={activeVariant}
+                viewSettings={viewSettings}
+                uiState={uiState}
+                uiActions={uiActions}
+                figmaUrl={figmaUrl}
+                linkCopied={uiState.linkCopied}
+                onCopyLink={handleCopyLink}
+              />
+
+              {/* Variant Tabs */}
+              {activeSegment.segment.variants && activeSegment.segment.variants.length > 0 && (
+                <VariantTabsBar
+                  variants={activeSegment.segment.variants}
+                  activeIndex={activeVariantIndex}
+                  onSelect={handleSelectVariant}
+                  showMatrixView={uiState.showMatrixView}
+                  showMultiViewport={uiState.showMultiViewport}
+                  onToggleMatrix={() => uiActions.setMatrixView(!uiState.showMatrixView)}
+                  onToggleMultiViewport={() => uiActions.setMultiViewport(!uiState.showMultiViewport)}
+                />
+              )}
+
+              {/* Preview Area */}
+              <div
+                className="flex-1 overflow-auto relative"
+                style={uiState.showMatrixView ? undefined : getBackgroundStyle(viewSettings.background)}
+              >
+                {activeVariant ? (
+                  <PreviewArea
+                    componentName={activeSegment.segment.meta.name}
+                    segmentPath={activeSegment.path}
+                    variant={activeVariant}
+                    variants={activeSegment.segment.variants}
+                    zoom={viewSettings.zoom}
+                    background={viewSettings.background}
+                    viewport={viewSettings.viewport}
+                    customSize={viewSettings.customSize}
+                    previewTheme={resolvedTheme}
+                    showMatrixView={uiState.showMatrixView}
+                    showMultiViewport={uiState.showMultiViewport}
+                    showComparison={uiState.showComparison}
+                    figmaUrl={figmaUrl}
+                    allFigmaUrls={allFigmaUrls}
+                    onSelectVariant={(index) => {
+                      uiActions.setMatrixView(false);
+                      handleSelectVariant(index);
+                    }}
+                    onRetry={uiActions.incrementPreviewKey}
+                    renderContent={renderVariantWithProps}
+                    previewKey={`${activeSegmentPath}-${activeVariantIndex}-${uiState.previewKey}`}
+                  />
+                ) : (
+                  <NoVariantsMessage segment={activeSegment?.segment} />
+                )}
+              </div>
+            </div>
+
+            {/* Bottom Panel */}
+            {activeVariant && (
+              <BottomPanel
+                segment={activeSegment.segment}
+                variant={activeVariant}
+                segments={segments}
+                activePanel={uiState.activePanel}
+                onPanelChange={uiActions.setActivePanel}
+                figmaUrl={figmaUrl}
+                figmaStyles={figmaIntegration.figmaStyles.status === 'success' ? figmaIntegration.figmaStyles.styles || null : null}
+                renderedStyles={figmaIntegration.renderedStyles}
+                figmaLoading={figmaIntegration.isLoading}
+                figmaError={figmaIntegration.errorMessage}
+                onFetchFigma={figmaIntegration.fetchFigmaStyles}
+                onRefreshRendered={figmaIntegration.extractRenderedStyles}
+                actionLogs={actionLogs}
+                onClearActionLogs={clearActionLogs}
+                onNavigateToComponent={(name) => {
+                  const target = segments.find(s => s.segment.meta.name === name);
+                  if (target) handleSelectSegment(target.path);
+                }}
+                previewKey={uiState.previewKey}
+                segmentKey={`${activeSegmentPath}-${activeVariantIndex}`}
+              />
+            )}
+          </div>
+        ) : (
+          <div className="flex flex-col items-center justify-center h-full text-secondary">
+            <EmptyIcon className="w-12 h-12 mb-4 text-[--text-muted]" />
+            <p className="text-base font-medium text-primary">No component selected</p>
+            <p className="text-sm mt-1 text-tertiary">Select a component from the sidebar</p>
+          </div>
+        )}
+      </Layout>
+    </>
+  );
+}
+
+// Top Toolbar Component
+interface TopToolbarProps {
+  segment: { path: string; segment: SegmentDefinition };
+  variant: any;
+  viewSettings: ReturnType<typeof useViewSettings>;
+  uiState: ReturnType<typeof useAppState>['state'];
+  uiActions: ReturnType<typeof useAppState>['actions'];
+  figmaUrl?: string;
+  linkCopied: boolean;
+  onCopyLink: () => void;
+}
+
+function TopToolbar({ segment, variant, viewSettings, uiState, uiActions, figmaUrl, linkCopied, onCopyLink }: TopToolbarProps) {
+  return (
+    <div className="flex items-center justify-between px-4 py-2 border-b border-[--border] bg-[--bg-secondary] flex-shrink-0">
+      <div className="flex items-center gap-3">
+        <h1 className="text-sm font-medium text-primary">{segment.segment.meta.name}</h1>
+        <span className="text-xs text-tertiary">{segment.segment.meta.category}</span>
+      </div>
+      <div className="flex items-center gap-2">
+        <PreviewToolbar
+          zoom={viewSettings.zoom}
+          background={viewSettings.background}
+          onZoomChange={viewSettings.setZoom}
+          onBackgroundChange={viewSettings.setBackground}
+        />
+        <div className="w-px h-4 bg-[--border]" />
+        <ViewportSelector
+          viewport={viewSettings.viewport}
+          customSize={viewSettings.customSize}
+          onViewportChange={viewSettings.setViewport}
+          onCustomSizeChange={viewSettings.setCustomSize}
+        />
+        <div className="w-px h-4 bg-[--border]" />
+
+        {figmaUrl && (
+          <>
+            <button
+              onClick={uiActions.toggleComparison}
+              className={clsx(
+                "p-1.5 rounded transition-colors",
+                uiState.showComparison
+                  ? "text-[--color-accent] bg-[--bg-hover]"
+                  : "text-tertiary hover:text-primary hover:bg-[--bg-hover]"
+              )}
+              title={uiState.showComparison ? "Hide Figma comparison" : "Compare with Figma design"}
+            >
+              <CompareIcon className="w-4 h-4" />
+            </button>
+            <button
+              onClick={() => window.open(figmaUrl, '_blank', 'noopener,noreferrer')}
+              className="p-1.5 text-tertiary hover:text-primary hover:bg-[--bg-hover] rounded transition-colors"
+              title="View in Figma"
+            >
+              <FigmaIcon className="w-4 h-4" />
+            </button>
+            <div className="w-px h-4 bg-[--border]" />
+          </>
+        )}
+
+        {variant && (
+          <>
+            <button
+              onClick={() => {
+                const url = new URL(window.location.href);
+                // Clear the hash to avoid malformed URLs
+                url.hash = '';
+                url.searchParams.set('isolated', 'true');
+                url.searchParams.set('component', segment.segment.meta.name);
+                url.searchParams.set('variant', variant.name);
+                if (viewSettings.zoom !== 100) url.searchParams.set('zoom', String(viewSettings.zoom));
+                if (viewSettings.background !== 'transparent') url.searchParams.set('bg', viewSettings.background);
+                window.open(url.toString(), '_blank', 'noopener,noreferrer');
+              }}
+              className="p-1.5 text-tertiary hover:text-primary hover:bg-[--bg-hover] rounded transition-colors"
+              title="Open in new window"
+            >
+              <ExternalLinkIcon className="w-4 h-4" />
+            </button>
+            <ScreenshotButton componentName={segment.segment.meta.name} variantName={variant.name} />
+            <button
+              onClick={onCopyLink}
+              className={clsx(
+                "p-1.5 rounded transition-colors",
+                linkCopied
+                  ? "text-green-600 bg-green-100 dark:bg-green-900/30"
+                  : "text-tertiary hover:text-primary hover:bg-[--bg-hover]"
+              )}
+              title="Copy link to share"
+            >
+              {linkCopied ? <CheckIcon className="w-4 h-4" /> : <LinkIcon className="w-4 h-4" />}
+            </button>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// Variant Tabs Bar Component
+interface VariantTabsBarProps {
+  variants: any[];
+  activeIndex: number;
+  onSelect: (index: number) => void;
+  showMatrixView: boolean;
+  showMultiViewport: boolean;
+  onToggleMatrix: () => void;
+  onToggleMultiViewport: () => void;
+}
+
+function VariantTabsBar({ variants, activeIndex, onSelect, showMatrixView, showMultiViewport, onToggleMatrix, onToggleMultiViewport }: VariantTabsBarProps) {
+  return (
+    <div className="px-4 py-2 border-b border-[--border] bg-[--bg-primary] flex-shrink-0 flex items-center justify-between">
+      {!showMatrixView ? (
+        <VariantTabs variants={variants} activeIndex={activeIndex} onSelect={onSelect} />
+      ) : (
+        <div className="text-sm text-secondary">Showing all {variants.length} variants</div>
+      )}
+      <div className="flex items-center gap-2 ml-4">
+        {variants.length > 1 && (
+          <button
+            onClick={onToggleMatrix}
+            className={clsx(
+              "flex items-center gap-1.5 px-2 py-1 rounded text-xs font-medium transition-colors",
+              showMatrixView
+                ? "bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-300"
+                : "text-tertiary hover:text-secondary hover:bg-[--bg-hover]"
+            )}
+            title={showMatrixView ? "Show single variant" : "Show all variants in grid"}
+          >
+            <GridIcon className="w-4 h-4" />
+            {showMatrixView ? "Exit Matrix" : "Matrix"}
+          </button>
+        )}
+        <button
+          onClick={onToggleMultiViewport}
+          className={clsx(
+            "flex items-center gap-1.5 px-2 py-1 rounded text-xs font-medium transition-colors",
+            showMultiViewport
+              ? "bg-green-100 dark:bg-green-900/30 text-green-700 dark:text-green-300"
+              : "text-tertiary hover:text-secondary hover:bg-[--bg-hover]"
+          )}
+          title={showMultiViewport ? "Exit multi-viewport" : "Show at multiple screen sizes"}
+        >
+          <DevicesIcon className="w-4 h-4" />
+          {showMultiViewport ? "Exit Responsive" : "Responsive"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// No variants message
+interface NoVariantsMessageProps {
+  segment?: SegmentDefinition;
+}
+
+function NoVariantsMessage({ segment }: NoVariantsMessageProps) {
+  const skippedVariants = (segment?._generated as any)?.skippedVariants;
+
+  if (!skippedVariants || skippedVariants.length === 0) {
+    return <div className="flex items-center justify-center h-full text-secondary text-sm">No variants defined</div>;
+  }
+
+  return (
+    <div className="flex items-center justify-center h-full p-6">
+      <div className="p-6 bg-sky-50 dark:bg-sky-950 border border-sky-300 dark:border-sky-700 rounded-lg max-w-lg">
+        <div className="flex items-start gap-3">
+          <div className="flex-shrink-0 w-8 h-8 rounded-full bg-sky-200 dark:bg-sky-800 flex items-center justify-center">
+            <span className="text-sky-700 dark:text-sky-200 text-lg">ℹ</span>
+          </div>
+          <div className="flex-1 min-w-0">
+            <h3 className="text-sm font-semibold text-sky-900 dark:text-sky-100">
+              {skippedVariants.length} variant{skippedVariants.length === 1 ? '' : 's'} skipped
+            </h3>
+            <p className="mt-1 text-xs text-sky-800 dark:text-sky-200">
+              These variants couldn't be rendered because they use syntax the parser doesn't support yet:
+            </p>
+            <ul className="mt-2 space-y-1">
+              {skippedVariants.map((sv: any, i: number) => (
+                <li key={i} className="text-xs text-sky-800 dark:text-sky-200">
+                  <span className="font-semibold">{sv.name}:</span>{' '}
+                  <span className="text-sky-700 dark:text-sky-300">{sv.reason}</span>
+                </li>
+              ))}
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Empty variant message
+interface EmptyVariantMessageProps {
+  reason: string;
+  variantName: string;
+  hint?: string;
+}
+
+function EmptyVariantMessage({ reason, variantName, hint }: EmptyVariantMessageProps) {
+  return (
+    <div className="p-6 bg-amber-50 dark:bg-amber-950 border border-amber-300 dark:border-amber-700 rounded-lg max-w-md">
+      <div className="flex items-start gap-3">
+        <div className="flex-shrink-0 w-8 h-8 rounded-full bg-amber-200 dark:bg-amber-800 flex items-center justify-center">
+          <span className="text-amber-700 dark:text-amber-200 text-lg">⚠</span>
+        </div>
+        <div className="flex-1 min-w-0">
+          <h3 className="text-sm font-semibold text-amber-900 dark:text-amber-100">
+            Variant "{variantName}" rendered empty
+          </h3>
+          <p className="mt-1 text-xs text-amber-800 dark:text-amber-200">{reason}</p>
+          {hint && (
+            <p className="mt-2 text-xs text-amber-700 dark:text-amber-300">
+              <strong>Tip:</strong> {hint}
+            </p>
+          )}
+          <div className="mt-3 text-xs text-amber-700 dark:text-amber-300">
+            <strong>Common causes:</strong>
+            <ul className="mt-1 ml-4 list-disc space-y-0.5">
+              <li>Component requires props that weren't provided</li>
+              <li>Component renders conditionally and conditions aren't met</li>
+              <li>Story args reference variables that don't exist in this context</li>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}