@fragments-sdk/viewer 0.2.1

package/src/components/App.tsx

@@ -0,0 +1,604 @@
+/**
+ * Main App component for the Fragments viewer.
+ * Refactored for better performance and maintainability.
+ */
+
+import { useState, useMemo, useEffect, useCallback, useRef, type ReactNode } from "react";
+import type { FragmentDefinition, FragmentVariant } from '@fragments-sdk/core';
+
+// Layout & Navigation
+import { Layout } from "./Layout.js";
+import { LeftSidebar } from "./LeftSidebar.js";
+import { CommandPalette } from "./CommandPalette.js";
+import { KeyboardShortcutsHelp } from "./KeyboardShortcutsHelp.js";
+import { useToast } from "./Toast.js";
+
+// Toolbar & Header
+import { TopToolbar } from "./TopToolbar.js";
+import { ViewerHeader } from "./ViewerHeader.js";
+
+// Preview & Rendering
+import { PreviewArea } from "./PreviewArea.js";
+import { BottomPanel } from "./BottomPanel.js";
+import { IsolatedRender } from "./IsolatedRender.js";
+import { FragmentRenderer, LoaderIndicator } from "./FragmentRenderer.js";
+import { HealthDashboard } from "./HealthDashboard.js";
+import { useAllFigmaUrls } from "./FigmaEmbed.js";
+import { ActionCapture } from "./ActionCapture.js";
+
+// Extracted sub-components
+import { PreviewAside } from "./PreviewAside.js";
+import { AllVariantsPreview } from "./AllVariantsPreview.js";
+import { ComponentDocView } from "./ComponentDocView.js";
+import { NoVariantsMessage } from "./NoVariantsMessage.js";
+import { EmptyVariantMessage } from "./EmptyVariantMessage.js";
+
+// Fragments UI
+import { Stack, Box, EmptyState } from "@fragments-sdk/ui";
+
+// Icons
+import { EmptyIcon } from "./Icons.js";
+
+// Utilities
+import { getVariantSectionId } from "./viewer-utils.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, findFragmentByName, findVariantIndex } from "../hooks/useUrlState.js";
+import { useTheme } from "./ThemeProvider.js";
+import { ViewerStateSync } from "./ViewerStateSync.js";
+
+interface AppProps {
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
+}
+
+export function App({ fragments }: 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, viewport, theme)
+  const viewSettings = useViewSettings({
+    initialState: {
+      zoom: urlState.zoom as any,
+      viewport: urlState.viewport as any,
+      customSize: { width: urlState.customWidth, height: urlState.customHeight },
+    },
+    onZoomChange: (zoom) => setUrlViewSettings({ zoom }),
+    onViewportChange: (vp, size) =>
+      setUrlViewSettings({
+        viewport: vp,
+        customWidth: size?.width,
+        customHeight: size?.height,
+      }),
+  });
+
+  // Get resolved theme from ThemeProvider for iframe preview
+  const { resolvedTheme } = useTheme();
+
+  // Toast notifications (via Fragments UI ToastProvider)
+  const { info, success } = useToast();
+
+  // Navigation state
+  const [activeFragmentPath, setActiveFragmentPath] = useState<string | null>(() => {
+    if (urlState.component) {
+      const found = findFragmentByName(fragments, urlState.component);
+      return found?.path ?? fragments[0]?.path ?? null;
+    }
+    return fragments[0]?.path ?? null;
+  });
+  const activeFragmentPathRef = useRef(activeFragmentPath);
+  activeFragmentPathRef.current = activeFragmentPath;
+
+  const [activeVariantIndex, setActiveVariantIndex] = useState<number>(() => {
+    const fragment = fragments.find((s) => s.path === activeFragmentPath);
+    if (urlState.variant && fragment?.fragment.variants) {
+      return findVariantIndex(fragment.fragment.variants, urlState.variant);
+    }
+    return 0;
+  });
+  const [searchQuery, setSearchQuery] = useState("");
+  const searchInputRef = useRef<HTMLInputElement>(null);
+
+  // Derived values
+  const activeFragment = useMemo(
+    () => fragments.find((s) => s.path === activeFragmentPath),
+    [fragments, activeFragmentPath]
+  );
+  const variants = activeFragment?.fragment.variants ?? [];
+  const variantCount = variants.length;
+  const safeVariantIndex = variantCount > 0 ? Math.min(activeVariantIndex, variantCount - 1) : 0;
+  const activeVariant = variants[safeVariantIndex];
+  const figmaUrl = activeVariant?.figma || activeFragment?.fragment.meta.figma;
+
+  // Figma integration
+  const figmaIntegration = useFigmaIntegration({
+    figmaUrl,
+    showComparison: uiState.showComparison,
+    dependencies: [activeFragmentPath, activeVariantIndex],
+  });
+
+  // Actions logging
+  const { logs: actionLogs, logAction, clearLogs: clearActionLogs } = useActions();
+  const useActionsRef = useRef({ logAction });
+  useActionsRef.current = { logAction };
+
+  // Figma URLs for preloading
+  const allFigmaUrls = useAllFigmaUrls(activeFragment?.fragment);
+
+  // Reset action logs on variant change
+  useEffect(() => {
+    clearActionLogs();
+  }, [activeFragmentPath, 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,
+  ]);
+
+  // Keep focused variant index in range when variant lists change.
+  useEffect(() => {
+    if (variantCount === 0) {
+      setActiveVariantIndex(0);
+      return;
+    }
+    if (activeVariantIndex >= variantCount) {
+      setActiveVariantIndex(variantCount - 1);
+    }
+  }, [activeVariantIndex, variantCount]);
+
+  // Sync URL state on browser navigation
+  useEffect(() => {
+    if (urlState.component) {
+      const found = findFragmentByName(fragments, urlState.component);
+      if (!found) return;
+
+      const pathChanged = found.path !== activeFragmentPathRef.current;
+      setActiveFragmentPath(found.path);
+      uiActions.setHealthDashboard(false);
+
+      // Keep focused variant when entering "All" on the same component.
+      if (urlState.variant || pathChanged) {
+        const variantIndex = findVariantIndex(found.fragment.variants, urlState.variant);
+        setActiveVariantIndex(variantIndex);
+      }
+    }
+  }, [urlState.component, urlState.variant, fragments, uiActions]);
+
+  // HMR toast notifications — batched so rapid bursts show one toast
+  useEffect(() => {
+    const hot = (import.meta as any).hot;
+    if (!hot) return;
+
+    let pending = new Set<string>();
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const flush = () => {
+      timer = null;
+      if (pending.size === 0) return;
+      const unique = Array.from(pending);
+      pending = new Set();
+      const summary =
+        unique.length <= 3
+          ? unique.join(", ")
+          : `${unique.slice(0, 3).join(", ")} +${unique.length - 3} more`;
+      info("HMR Update", `Updated: ${summary}`);
+    };
+
+    const handleUpdate = (data: any) => {
+      if (data?.updates?.length > 0) {
+        for (const u of data.updates) {
+          pending.add(u.path.split("/").pop());
+        }
+        // Debounce: wait 100ms for more updates before showing toast
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(flush, 100);
+      }
+    };
+
+    hot.on("vite:beforeUpdate", handleUpdate);
+    return () => {
+      hot.off?.("vite:beforeUpdate", handleUpdate);
+      if (timer) clearTimeout(timer);
+    };
+  }, [info]);
+
+  // Navigation handlers
+  const handleSelectFragment = useCallback(
+    (path: string) => {
+      const fragment = fragments.find((s) => s.path === path);
+      const componentName = fragment?.fragment.meta.name || path;
+
+      setActiveFragmentPath(path);
+      setActiveVariantIndex(0);
+      uiActions.setHealthDashboard(false);
+      setUrlComponent(componentName, null);
+    },
+    [fragments, setUrlComponent, uiActions]
+  );
+
+  const scrollToVariantSection = useCallback(
+    (index: number, behavior: ScrollBehavior = "smooth") => {
+      if (!activeFragment || variantCount === 0) return;
+      const normalizedIndex = ((index % variantCount) + variantCount) % variantCount;
+      const targetVariant = variants[normalizedIndex];
+      if (!targetVariant) return;
+
+      const sectionId = getVariantSectionId(activeFragment.fragment.meta.name, targetVariant.name);
+      document.getElementById(sectionId)?.scrollIntoView({ behavior, block: "start" });
+    },
+    [activeFragment, variantCount, variants]
+  );
+
+  const focusVariantInAllMode = useCallback(
+    (index: number, shouldScroll = false) => {
+      if (variantCount === 0) return;
+      const normalizedIndex = ((index % variantCount) + variantCount) % variantCount;
+      setActiveVariantIndex(normalizedIndex);
+      if (shouldScroll) {
+        scrollToVariantSection(normalizedIndex);
+      }
+    },
+    [variantCount, scrollToVariantSection]
+  );
+
+  const handleSelectVariant = useCallback(
+    (index: number) => {
+      if (variantCount === 0) return;
+      const normalizedIndex = ((index % variantCount) + variantCount) % variantCount;
+      const variantName = variants[normalizedIndex]?.name;
+      setActiveVariantIndex(normalizedIndex);
+      setUrlVariant(variantName || null);
+    },
+    [variantCount, variants, setUrlVariant]
+  );
+
+  const handleSelectVariantLink = useCallback(
+    (index: number) => {
+      // Always scroll to the variant section in the docs-like view
+      focusVariantInAllMode(index, true);
+    },
+    [focusVariantInAllMode]
+  );
+
+  // Copy link handler
+  const handleCopyLink = useCallback(async () => {
+    const copied = await copyUrl();
+    if (copied) {
+      uiActions.setLinkCopied(true);
+      success("Copied", "Link copied to clipboard");
+      setTimeout(() => uiActions.setLinkCopied(false), 2000);
+    }
+  }, [copyUrl, success, uiActions]);
+
+  // Sorted fragment paths for keyboard navigation
+  const sortedFragmentPaths = useMemo(() => {
+    return [...fragments]
+      .filter((s) => s.fragment?.meta?.name)
+      .sort((a, b) => a.fragment.meta.name.localeCompare(b.fragment.meta.name))
+      .map((s) => s.path);
+  }, [fragments]);
+
+  const currentFragmentIndex = sortedFragmentPaths.indexOf(activeFragmentPath || "");
+
+  // Keyboard shortcuts
+  useKeyboardShortcuts(
+    {
+      nextComponent: () => {
+        const nextIndex =
+          currentFragmentIndex < sortedFragmentPaths.length - 1 ? currentFragmentIndex + 1 : 0;
+        handleSelectFragment(sortedFragmentPaths[nextIndex]);
+      },
+      prevComponent: () => {
+        const prevIndex =
+          currentFragmentIndex > 0 ? currentFragmentIndex - 1 : sortedFragmentPaths.length - 1;
+        handleSelectFragment(sortedFragmentPaths[prevIndex]);
+      },
+      nextVariant: () => {
+        if (variantCount === 0) return;
+        const nextIndex = activeVariantIndex < variantCount - 1 ? activeVariantIndex + 1 : 0;
+        focusVariantInAllMode(nextIndex, true);
+      },
+      prevVariant: () => {
+        if (variantCount === 0) return;
+        const prevIndex = activeVariantIndex > 0 ? activeVariantIndex - 1 : variantCount - 1;
+        focusVariantInAllMode(prevIndex, true);
+      },
+      goToVariant: (index) => {
+        if (index >= variantCount) return;
+        focusVariantInAllMode(index, true);
+      },
+      toggleTheme: viewSettings.toggleTheme,
+      togglePanel: uiActions.togglePanel,
+      toggleMatrix: () => uiActions.setMatrixView(!uiState.showMatrixView),
+      toggleResponsive: () => uiActions.setMultiViewport(!uiState.showMultiViewport),
+      copyLink: handleCopyLink,
+      showHelp: uiActions.toggleShortcutsHelp,
+      openSearch: () => uiActions.setCommandPalette(true),
+      escape: () => {
+        if (document.activeElement === searchInputRef.current) {
+          if (searchQuery) {
+            setSearchQuery("");
+          } else {
+            searchInputRef.current.blur();
+          }
+          return;
+        }
+        uiActions.closeAllModals();
+      },
+    },
+    { enabled: !uiState.showShortcutsHelp, variantCount }
+  );
+
+  // Render variant with action logging via DOM event capture
+  const renderVariantWithProps = useCallback((variant: FragmentVariant | undefined) => {
+    if (!variant) return null;
+
+    return (
+      <ActionCapture onAction={useActionsRef.current.logAction}>
+        <FragmentRenderer variant={variant}>
+          {(content, isLoading, error) => {
+            if (isLoading)
+              return (
+                <Stack align="center" justify="center" style={{ padding: "32px" }}>
+                  <LoaderIndicator />
+                </Stack>
+              );
+            if (error)
+              return (
+                <EmptyVariantMessage
+                  reason={`Error: ${error.message}`}
+                  variantName={variant.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={variant.name}
+                  hint="The variant's render function didn't return any JSX."
+                />
+              );
+            return content;
+          }}
+        </FragmentRenderer>
+      </ActionCapture>
+    );
+  }, []);
+
+  // Check if isolated mode
+  const isIsolated = useMemo(() => {
+    const params = new URLSearchParams(window.location.search);
+    return params.get("isolated") === "true";
+  }, []);
+
+  if (isIsolated) {
+    return <IsolatedRender fragments={fragments} />;
+  }
+
+  return (
+    <>
+      <ViewerStateSync fragments={fragments} activeVariantIndex={safeVariantIndex} />
+      <KeyboardShortcutsHelp
+        isOpen={uiState.showShortcutsHelp}
+        onClose={() => uiActions.setShortcutsHelp(false)}
+      />
+      <CommandPalette
+        isOpen={uiState.showCommandPalette}
+        onClose={() => uiActions.setCommandPalette(false)}
+        fragments={fragments}
+        onSelectComponent={handleSelectFragment}
+        onSelectVariant={(path, variantIndex) => {
+          handleSelectFragment(path);
+          setTimeout(() => handleSelectVariant(variantIndex), 0);
+        }}
+      />
+
+      <Layout
+        header={
+          activeFragment && !uiState.showHealthDashboard ? (
+            <TopToolbar
+              fragment={activeFragment}
+              viewSettings={viewSettings}
+              uiState={uiState}
+              uiActions={uiActions}
+              figmaUrl={figmaUrl}
+              searchQuery={searchQuery}
+              onSearchChange={setSearchQuery}
+              searchInputRef={searchInputRef}
+            />
+          ) : (
+            <ViewerHeader
+              showHealth={uiState.showHealthDashboard}
+              searchQuery={searchQuery}
+              onSearchChange={setSearchQuery}
+              searchInputRef={searchInputRef}
+            />
+          )
+        }
+        leftSidebar={
+          <LeftSidebar
+            fragments={fragments}
+            activeFragment={uiState.showHealthDashboard ? null : activeFragmentPath}
+            searchQuery={searchQuery}
+            onSelect={handleSelectFragment}
+            showHealth={uiState.showHealthDashboard}
+            onHealthClick={() => {
+              uiActions.setHealthDashboard(true);
+              setActiveFragmentPath(null);
+            }}
+          />
+        }
+        aside={
+          uiState.showAside && activeFragment && !uiState.showHealthDashboard ? (
+            <PreviewAside
+              fragment={activeFragment.fragment}
+              variants={variants}
+              focusedVariantIndex={safeVariantIndex}
+              activePanel={uiState.activePanel}
+              onSelectVariant={handleSelectVariantLink}
+              onCopyLink={handleCopyLink}
+              onShowShortcuts={uiActions.toggleShortcutsHelp}
+            />
+          ) : null
+        }
+      >
+        {uiState.showHealthDashboard ? (
+          <Box height="100%" overflow="auto" background="primary">
+            <Box padding="lg" style={{ maxWidth: "896px", margin: "0 auto" }}>
+              <HealthDashboard
+                fragments={fragments}
+                onNavigate={(componentName) => {
+                  const target = fragments.find((s) => s.fragment.meta.name === componentName);
+                  if (target) {
+                    uiActions.setHealthDashboard(false);
+                    handleSelectFragment(target.path);
+                  }
+                }}
+              />
+            </Box>
+          </Box>
+        ) : activeFragment ? (
+          <Stack id="preview-layout" style={{ height: "100%" }}>
+            {/* Main Content Area */}
+            <Stack style={{ flex: 1, minWidth: 0, minHeight: 0 }}>
+              {/* Preview Area */}
+              <Box id="preview-canvas" overflow="auto" style={{ flex: 1, position: "relative" }}>
+                {variantCount === 0 ? (
+                  <NoVariantsMessage fragment={activeFragment?.fragment} />
+                ) : uiState.showMatrixView ? (
+                  <PreviewArea
+                    componentName={activeFragment.fragment.meta.name}
+                    fragmentPath={activeFragment.path}
+                    variant={activeVariant}
+                    variants={variants}
+                    zoom={viewSettings.zoom}
+                    viewport={viewSettings.viewport}
+                    customSize={viewSettings.customSize}
+                    previewTheme={resolvedTheme}
+                    showMatrixView={true}
+                    showMultiViewport={false}
+                    showComparison={uiState.showComparison}
+                    figmaUrl={figmaUrl}
+                    allFigmaUrls={allFigmaUrls}
+                    onSelectVariant={(index) => {
+                      uiActions.setMatrixView(false);
+                      handleSelectVariant(index);
+                    }}
+                    onRetry={uiActions.incrementPreviewKey}
+                    renderContent={() => renderVariantWithProps(activeVariant)}
+                    previewKey={`${activeFragmentPath}-${safeVariantIndex}-${uiState.previewKey}`}
+                  />
+                ) : uiState.showMultiViewport ? (
+                  <PreviewArea
+                    componentName={activeFragment.fragment.meta.name}
+                    fragmentPath={activeFragment.path}
+                    variant={activeVariant}
+                    variants={variants}
+                    zoom={viewSettings.zoom}
+                    viewport={viewSettings.viewport}
+                    customSize={viewSettings.customSize}
+                    previewTheme={resolvedTheme}
+                    showMatrixView={false}
+                    showMultiViewport={true}
+                    showComparison={uiState.showComparison}
+                    figmaUrl={figmaUrl}
+                    allFigmaUrls={allFigmaUrls}
+                    onSelectVariant={(index) => {
+                      handleSelectVariant(index);
+                    }}
+                    onRetry={uiActions.incrementPreviewKey}
+                    renderContent={() => renderVariantWithProps(activeVariant)}
+                    previewKey={`${activeFragmentPath}-${safeVariantIndex}-${uiState.previewKey}`}
+                  />
+                ) : (
+                  <Box
+                    style={{
+                      padding: "var(--fui-space-6) var(--fui-space-8)",
+                    }}
+                  >
+                    <ComponentDocView
+                      fragment={activeFragment}
+                      fragments={fragments}
+                      renderVariantContent={renderVariantWithProps}
+                      onNavigateToComponent={(name) => {
+                        const target = fragments.find((s) => s.fragment.meta.name === name);
+                        if (target) handleSelectFragment(target.path);
+                      }}
+                      zoom={viewSettings.zoom}
+                      viewport={viewSettings.viewport}
+                      customSize={viewSettings.customSize}
+                      previewTheme={resolvedTheme}
+                      showComparison={uiState.showComparison}
+                      allFigmaUrls={allFigmaUrls}
+                      onRetry={uiActions.incrementPreviewKey}
+                      previewKeyBase={`${activeFragmentPath}-${uiState.previewKey}`}
+                    />
+                  </Box>
+                )}
+              </Box>
+            </Stack>
+
+            {activeVariant && (
+              <BottomPanel
+                fragment={activeFragment.fragment}
+                variant={activeVariant}
+                fragments={fragments}
+                open={uiState.panelOpen}
+                onOpenChange={uiActions.setPanelOpen}
+                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}
+                onNavigateToComponent={(name) => {
+                  const target = fragments.find((s) => s.fragment.meta.name === name);
+                  if (target) handleSelectFragment(target.path);
+                }}
+                previewKey={uiState.previewKey}
+                fragmentKey={`${activeFragmentPath}-${safeVariantIndex}`}
+              />
+            )}
+          </Stack>
+        ) : (
+          <EmptyState style={{ height: "100%" }}>
+            <EmptyState.Icon>
+              <EmptyIcon style={{ width: "48px", height: "48px" }} />
+            </EmptyState.Icon>
+            <EmptyState.Title>No component selected</EmptyState.Title>
+            <EmptyState.Description>Select a component from the sidebar</EmptyState.Description>
+          </EmptyState>
+        )}
+      </Layout>
+    </>
+  );
+}