@fragments-sdk/viewer 0.2.1

package/src/components/TopToolbar.tsx

@@ -0,0 +1,159 @@
+import type { RefObject } from "react";
+import type { FragmentDefinition } from '@fragments-sdk/core';
+import type { useViewSettings } from "../hooks/useViewSettings.js";
+import type { useAppState } from "../hooks/useAppState.js";
+import {
+  Header,
+  Stack,
+  Text,
+  Separator,
+  Tooltip,
+  Button,
+  ThemeToggle,
+  FragmentsLogo,
+} from "@fragments-sdk/ui";
+import { DeviceMobile, GridFour, SidebarSimple } from "@phosphor-icons/react";
+import { GitHubIcon, FigmaIcon, CompareIcon } from "./Icons.js";
+import { PreviewToolbar } from "./PreviewToolbar.js";
+import { HeaderSearch } from "./HeaderSearch.js";
+import { useTheme } from "./ThemeProvider.js";
+import { WebMCPStatusIndicator } from "./WebMCPStatusIndicator.js";
+
+/** Normalize category to Title Case for display */
+function titleCase(str: string): string {
+  return str.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+interface TopToolbarProps {
+  fragment: { path: string; fragment: FragmentDefinition };
+  viewSettings: ReturnType<typeof useViewSettings>;
+  uiState: ReturnType<typeof useAppState>["state"];
+  uiActions: ReturnType<typeof useAppState>["actions"];
+  figmaUrl?: string;
+  searchQuery: string;
+  onSearchChange: (value: string) => void;
+  searchInputRef: RefObject<HTMLInputElement>;
+}
+
+export function TopToolbar({
+  fragment,
+  viewSettings,
+  uiState,
+  uiActions,
+  figmaUrl,
+  searchQuery,
+  onSearchChange,
+  searchInputRef,
+}: TopToolbarProps) {
+  const { setTheme, resolvedTheme } = useTheme();
+  return (
+    <Header aria-label="Component preview toolbar">
+      <Header.Trigger />
+      <Header.Brand>
+        <Stack direction="row" align="center" gap="sm">
+          <FragmentsLogo size={20} />
+          <Text weight="medium" size="sm">
+            {fragment.fragment.meta.name}
+          </Text>
+          <Text size="xs" color="tertiary">
+            {titleCase(fragment.fragment.meta.category || '')}
+          </Text>
+        </Stack>
+      </Header.Brand>
+      <HeaderSearch value={searchQuery} onChange={onSearchChange} inputRef={searchInputRef} />
+      <Header.Spacer />
+      <Header.Actions>
+        <PreviewToolbar zoom={viewSettings.zoom} onZoomChange={viewSettings.setZoom} />
+        <Separator orientation="vertical" style={{ height: "16px" }} />
+        <Tooltip content={uiState.showMatrixView ? "Disable matrix view" : "Enable matrix view"}>
+          <Button
+            variant={uiState.showMatrixView ? "secondary" : "ghost"}
+            size="sm"
+            icon
+            aria-pressed={uiState.showMatrixView}
+            aria-label="Toggle matrix view"
+            onClick={() => uiActions.setMatrixView(!uiState.showMatrixView)}
+          >
+            <GridFour size={16} />
+          </Button>
+        </Tooltip>
+        <Tooltip
+          content={uiState.showMultiViewport ? "Disable responsive view" : "Enable responsive view"}
+        >
+          <Button
+            variant={uiState.showMultiViewport ? "secondary" : "ghost"}
+            size="sm"
+            icon
+            aria-pressed={uiState.showMultiViewport}
+            aria-label="Toggle responsive view"
+            onClick={() => uiActions.setMultiViewport(!uiState.showMultiViewport)}
+          >
+            <DeviceMobile size={16} />
+          </Button>
+        </Tooltip>
+        <Separator orientation="vertical" style={{ height: "16px" }} />
+        {figmaUrl && (
+          <>
+            <Tooltip
+              content={
+                uiState.showComparison ? "Hide Figma comparison" : "Compare with Figma design"
+              }
+            >
+              <Button
+                variant={uiState.showComparison ? "secondary" : "ghost"}
+                size="sm"
+                icon
+                onClick={uiActions.toggleComparison}
+              >
+                <CompareIcon style={{ width: "16px", height: "16px" }} />
+              </Button>
+            </Tooltip>
+            <Tooltip content="View in Figma">
+              <Button
+                onClick={() => window.open(figmaUrl, "_blank", "noopener,noreferrer")}
+                variant="ghost"
+                size="sm"
+                icon
+              >
+                <FigmaIcon style={{ width: "16px", height: "16px" }} />
+              </Button>
+            </Tooltip>
+            <Separator orientation="vertical" style={{ height: "16px" }} />
+          </>
+        )}
+        <WebMCPStatusIndicator />
+        <Tooltip content={uiState.showAside ? "Hide side panel" : "Show side panel"}>
+          <Button
+            variant={uiState.showAside ? "secondary" : "ghost"}
+            size="sm"
+            icon
+            aria-pressed={uiState.showAside}
+            aria-label="Toggle side panel"
+            onClick={uiActions.toggleAside}
+          >
+            <SidebarSimple size={16} style={{ transform: "scaleX(-1)" }} />
+          </Button>
+        </Tooltip>
+        <Separator orientation="vertical" style={{ height: "16px" }} />
+        <ThemeToggle
+          size="sm"
+          value={resolvedTheme}
+          onValueChange={(value) => setTheme(value)}
+          aria-label={`Theme: ${resolvedTheme}`}
+        />
+        <Button
+          as="a"
+          variant="ghost"
+          size="sm"
+          icon
+          href="https://github.com/ConanMcN/fragments"
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label="View on GitHub"
+        >
+          <GitHubIcon />
+        </Button>
+      </Header.Actions>
+    </Header>
+  );
+}

package/src/components/Untitled

@@ -0,0 +1 @@
+400px

package/src/components/UsageSection.tsx

@@ -0,0 +1,95 @@
+import type { FragmentUsage } from '@fragments-sdk/core';
+import { CheckIcon, XIcon, AccessibilityIcon } from './Icons.js';
+
+interface UsageSectionProps {
+  usage: FragmentUsage;
+}
+
+export function UsageSection({ usage }: UsageSectionProps) {
+  const hasWhen = usage.when && usage.when.length > 0;
+  const hasWhenNot = usage.whenNot && usage.whenNot.length > 0;
+  const hasGuidelines = usage.guidelines && usage.guidelines.length > 0;
+  const hasAccessibility = usage.accessibility && usage.accessibility.length > 0;
+
+  if (!hasWhen && !hasWhenNot && !hasGuidelines && !hasAccessibility) {
+    return null;
+  }
+
+  return (
+    <section id="usage" style={{ scrollMarginTop: '96px' }}>
+      <h2 style={{ fontSize: '16px', fontWeight: 600, color: 'var(--text-primary)', marginBottom: '20px' }}>Usage</h2>
+
+      {/* When to use / When not to use */}
+      {(hasWhen || hasWhenNot) && (
+        <div style={{ display: 'grid', gridTemplateColumns: hasWhen && hasWhenNot ? '1fr 1fr' : '1fr', gap: '32px', marginBottom: '32px' }}>
+          {hasWhen && (
+            <div style={{ padding: '16px', borderRadius: '12px', background: 'var(--color-success-bg)', border: '1px solid rgba(16, 163, 127, 0.2)' }}>
+              <h3 style={{ fontSize: '13px', fontWeight: 500, color: 'var(--color-success)', marginBottom: '12px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+                <CheckIcon style={{ width: '16px', height: '16px' }} />
+                When to use
+              </h3>
+              <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'flex', flexDirection: 'column', gap: '8px' }}>
+                {usage.when!.map((item, index) => (
+                  <li key={index} style={{ fontSize: '13px', color: 'var(--text-primary)', lineHeight: 1.6, display: 'flex', alignItems: 'flex-start', gap: '8px' }}>
+                    <span style={{ color: 'var(--color-success)', marginTop: '6px', fontSize: '12px' }}>&#8226;</span>
+                    <span>{item}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          {hasWhenNot && (
+            <div style={{ padding: '16px', borderRadius: '12px', background: 'var(--color-danger-bg)', border: '1px solid rgba(239, 68, 68, 0.2)' }}>
+              <h3 style={{ fontSize: '13px', fontWeight: 500, color: 'var(--color-danger)', marginBottom: '12px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+                <XIcon style={{ width: '16px', height: '16px' }} />
+                When not to use
+              </h3>
+              <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'flex', flexDirection: 'column', gap: '8px' }}>
+                {usage.whenNot!.map((item, index) => (
+                  <li key={index} style={{ fontSize: '13px', color: 'var(--text-primary)', lineHeight: 1.6, display: 'flex', alignItems: 'flex-start', gap: '8px' }}>
+                    <span style={{ color: 'var(--color-danger)', marginTop: '6px', fontSize: '12px' }}>&#8226;</span>
+                    <span>{item}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Guidelines */}
+      {hasGuidelines && (
+        <div style={{ marginBottom: '24px' }}>
+          <h3 style={{ fontSize: '13px', fontWeight: 500, color: 'var(--text-primary)', marginBottom: '12px' }}>Guidelines</h3>
+          <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'flex', flexDirection: 'column', gap: '8px' }}>
+            {usage.guidelines!.map((item, index) => (
+              <li key={index} style={{ fontSize: '13px', color: 'var(--text-secondary)', lineHeight: 1.6, display: 'flex', alignItems: 'flex-start', gap: '8px' }}>
+                <span style={{ color: 'var(--color-accent)', marginTop: '6px', fontSize: '12px' }}>&#8226;</span>
+                <span>{item}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Accessibility */}
+      {hasAccessibility && (
+        <div style={{ padding: '16px', borderRadius: '12px', border: '1px solid var(--border)', background: 'var(--bg-secondary)' }}>
+          <h3 style={{ fontSize: '13px', fontWeight: 500, color: 'var(--text-primary)', marginBottom: '12px', display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <AccessibilityIcon style={{ width: '16px', height: '16px', color: 'var(--text-secondary)' }} />
+            Accessibility
+          </h3>
+          <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'flex', flexDirection: 'column', gap: '8px' }}>
+            {usage.accessibility!.map((item, index) => (
+              <li key={index} style={{ fontSize: '13px', color: 'var(--text-secondary)', lineHeight: 1.6, display: 'flex', alignItems: 'flex-start', gap: '8px' }}>
+                <span style={{ color: 'var(--text-tertiary)', marginTop: '6px', fontSize: '12px' }}>&#8226;</span>
+                <span>{item}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </section>
+  );
+}

package/src/components/VariantMatrix.tsx

@@ -0,0 +1,391 @@
+// @ts-nocheck
+/**
+ * Variant Matrix View - Display all variants in a grid
+ *
+ * Shows all variants of a component simultaneously, making it easy to:
+ * - Compare states/variants at a glance
+ * - Spot visual inconsistencies
+ * - Review all component states quickly
+ *
+ * Uses virtualization to only render visible variants for better performance.
+ */
+
+import { useState, useMemo, useRef, useCallback } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { Box, Stack, Text, Button, Badge, EmptyState } from "@fragments-sdk/ui";
+import type { FragmentVariant } from '@fragments-sdk/core';
+import { ErrorBoundary } from "./ErrorBoundary.js";
+import { FragmentRenderer, LoaderIndicator } from "./FragmentRenderer.js";
+import { IsolatedPreviewFrame } from "./IsolatedPreviewFrame.js";
+import { ShadowPreview } from "./ShadowPreview.js";
+import { ChevronDownIcon } from "./Icons.js";
+
+interface VariantMatrixProps {
+  /** All variants to display */
+  variants: FragmentVariant[];
+  /** Component name for error display */
+  componentName: string;
+  /** Fragment path for iframe rendering */
+  fragmentPath: string;
+  /** Current zoom level */
+  zoom: number;
+  /** Preview theme */
+  previewTheme: "light" | "dark";
+  /** Whether to use iframe isolation */
+  useIframeIsolation?: boolean;
+  /** Callback when a variant is clicked to focus on it */
+  onSelectVariant?: (index: number) => void;
+}
+
+type GridSize = "small" | "medium" | "large";
+
+interface GridConfig {
+  gridTemplateColumns: string;
+  minHeight: string;
+  heightPx: number; // For virtualization
+  scale: number;
+  colCount: number; // Default column count for virtualization
+}
+
+const GRID_SIZES: Record<GridSize, GridConfig> = {
+  small: { gridTemplateColumns: "repeat(4, 1fr)", minHeight: "150px", heightPx: 150, scale: 0.5, colCount: 4 },
+  medium: { gridTemplateColumns: "repeat(3, 1fr)", minHeight: "200px", heightPx: 200, scale: 0.75, colCount: 3 },
+  large: { gridTemplateColumns: "repeat(2, 1fr)", minHeight: "300px", heightPx: 300, scale: 1, colCount: 2 },
+};
+
+/** Threshold for enabling virtualization */
+const VIRTUALIZATION_THRESHOLD = 12;
+
+export function VariantMatrix({
+  variants,
+  componentName,
+  fragmentPath,
+  zoom,
+  previewTheme,
+  useIframeIsolation = true,
+  onSelectVariant,
+}: VariantMatrixProps) {
+  const [gridSize, setGridSize] = useState<GridSize>("medium");
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  const gridConfig = GRID_SIZES[gridSize];
+  const effectiveScale = (zoom / 100) * gridConfig.scale;
+
+  // Determine if we should use virtualization
+  const useVirtualization = variants.length > VIRTUALIZATION_THRESHOLD;
+
+  // Calculate number of rows for virtualization
+  const columns = gridConfig.colCount;
+  const rowCount = Math.ceil(variants.length / columns);
+
+  // Row height includes card height + gap
+  const rowHeight = gridConfig.heightPx + 16; // 16px gap
+
+  const rowVirtualizer = useVirtualizer({
+    count: rowCount,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => rowHeight,
+    overscan: 2, // Render 2 extra rows above/below for smooth scrolling
+  });
+
+  if (variants.length === 0) {
+    return (
+      <EmptyState style={{ height: '100%' }}>
+        <EmptyState.Title>No variants to display</EmptyState.Title>
+      </EmptyState>
+    );
+  }
+
+  return (
+    <Stack style={{ height: '100%' }}>
+      {/* Toolbar */}
+      <Box paddingX="md" paddingY="sm" borderBottom background="secondary" style={{ flexShrink: 0 }}>
+        <Stack direction="row" align="center" justify="between">
+          <Text size="sm" color="secondary">
+            {variants.length} variant{variants.length !== 1 ? "s" : ""}
+            {useVirtualization && <Text as="span" size="xs" color="tertiary"> (virtualized)</Text>}
+          </Text>
+          <Stack direction="row" align="center" gap="sm">
+            <Text size="xs" color="tertiary">Grid size:</Text>
+            <Stack direction="row" style={{ borderRadius: 6, border: '1px solid var(--border)', overflow: 'hidden' }}>
+              {(["small", "medium", "large"] as GridSize[]).map((size) => (
+                <Button
+                  key={size}
+                  variant={gridSize === size ? "secondary" : "ghost"}
+                  size="sm"
+                  onClick={() => setGridSize(size)}
+                  style={{ textTransform: 'capitalize', borderRadius: 0 }}
+                >
+                  {size}
+                </Button>
+              ))}
+            </Stack>
+          </Stack>
+        </Stack>
+      </Box>
+
+      {/* Grid - Virtualized or Regular */}
+      {useVirtualization ? (
+        <Box ref={scrollRef} overflow="auto" padding="md" style={{ flex: 1 }}>
+          <div
+            style={{
+              height: `${rowVirtualizer.getTotalSize()}px`,
+              width: "100%",
+              position: "relative",
+            }}
+          >
+            {rowVirtualizer.getVirtualItems().map((virtualRow) => {
+              const startIndex = virtualRow.index * columns;
+              const rowVariants = variants.slice(startIndex, startIndex + columns);
+
+              return (
+                <div
+                  key={virtualRow.key}
+                  style={{
+                    position: "absolute",
+                    top: 0,
+                    left: 0,
+                    width: "100%",
+                    height: `${virtualRow.size}px`,
+                    transform: `translateY(${virtualRow.start}px)`,
+                  }}
+                >
+                  <div style={{
+                    display: 'grid',
+                    gap: 16,
+                    gridTemplateColumns: gridConfig.gridTemplateColumns,
+                    height: gridConfig.minHeight,
+                  }}>
+                    {rowVariants.map((variant, colIndex) => {
+                      const index = startIndex + colIndex;
+                      return (
+                        <VariantCard
+                          key={variant.name}
+                          variant={variant}
+                          index={index}
+                          componentName={componentName}
+                          fragmentPath={fragmentPath}
+                          scale={effectiveScale}
+                          minHeight={gridConfig.minHeight}
+                          previewTheme={previewTheme}
+                          useIframeIsolation={useIframeIsolation}
+                          isHovered={hoveredIndex === index}
+                          onHover={() => setHoveredIndex(index)}
+                          onLeave={() => setHoveredIndex(null)}
+                          onClick={() => onSelectVariant?.(index)}
+                        />
+                      );
+                    })}
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        </Box>
+      ) : (
+        <Box overflow="auto" padding="md" style={{ flex: 1 }}>
+          <div style={{
+            display: 'grid',
+            gap: 16,
+            gridTemplateColumns: gridConfig.gridTemplateColumns,
+          }}>
+            {variants.map((variant, index) => (
+              <VariantCard
+                key={variant.name}
+                variant={variant}
+                index={index}
+                componentName={componentName}
+                fragmentPath={fragmentPath}
+                scale={effectiveScale}
+                minHeight={gridConfig.minHeight}
+                previewTheme={previewTheme}
+                useIframeIsolation={useIframeIsolation}
+                isHovered={hoveredIndex === index}
+                onHover={() => setHoveredIndex(index)}
+                onLeave={() => setHoveredIndex(null)}
+                onClick={() => onSelectVariant?.(index)}
+              />
+            ))}
+          </div>
+        </Box>
+      )}
+    </Stack>
+  );
+}
+
+interface VariantCardProps {
+  variant: FragmentVariant;
+  index: number;
+  componentName: string;
+  fragmentPath: string;
+  scale: number;
+  minHeight: string;
+  previewTheme: "light" | "dark";
+  useIframeIsolation: boolean;
+  isHovered: boolean;
+  onHover: () => void;
+  onLeave: () => void;
+  onClick: () => void;
+}
+
+function VariantCard({
+  variant,
+  index,
+  componentName,
+  fragmentPath,
+  scale,
+  minHeight,
+  previewTheme,
+  useIframeIsolation,
+  isHovered,
+  onHover,
+  onLeave,
+  onClick,
+}: VariantCardProps) {
+  return (
+    <div
+      style={{
+        position: 'relative',
+        borderRadius: 8,
+        border: isHovered
+          ? '2px solid #3b82f6'
+          : '1px solid var(--border)',
+        overflow: 'hidden',
+        transition: 'border-color 0.2s, box-shadow 0.2s',
+        cursor: 'pointer',
+        minHeight,
+        boxShadow: isHovered
+          ? '0 10px 15px -3px rgba(0,0,0,0.1), 0 0 0 3px rgba(59,130,246,0.2)'
+          : 'none',
+      }}
+      onMouseEnter={onHover}
+      onMouseLeave={onLeave}
+      onClick={onClick}
+    >
+      {/* Header overlay - keep inline styles (CSS art) */}
+      <div style={{
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        zIndex: 10,
+        padding: '4px 8px',
+        background: 'linear-gradient(to bottom, rgba(0,0,0,0.6), transparent)',
+      }}>
+        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+          <span style={{
+            fontSize: 12,
+            fontWeight: 500,
+            color: '#ffffff',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}>
+            {variant.name}
+          </span>
+          <span style={{ fontSize: 10, color: 'rgba(255,255,255,0.7)' }}>
+            #{index + 1}
+          </span>
+        </div>
+      </div>
+
+      {/* Click to view overlay */}
+      <div
+        style={{
+          position: 'absolute',
+          inset: 0,
+          zIndex: 10,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: 'rgba(0,0,0,0.4)',
+          transition: 'opacity 0.2s',
+          opacity: isHovered ? 1 : 0,
+          pointerEvents: isHovered ? 'auto' : 'none',
+        }}
+      >
+        <span style={{
+          padding: '6px 12px',
+          background: '#2563eb',
+          color: '#ffffff',
+          fontSize: 12,
+          fontWeight: 500,
+          borderRadius: 9999,
+          boxShadow: '0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1)',
+        }}>
+          Click to focus
+        </span>
+      </div>
+
+      {/* Preview content */}
+      <div
+        data-theme={previewTheme}
+        style={{
+          height: '100%',
+          width: '100%',
+          overflow: 'hidden',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        {useIframeIsolation ? (
+          <IsolatedPreviewFrame
+            fragmentPath={fragmentPath}
+            variantName={variant.name}
+            theme={previewTheme}
+            width="100%"
+            height="100%"
+            minHeight={minHeight}
+          />
+        ) : (
+          <ShadowPreview theme={previewTheme} width="100%" height="100%" minHeight={minHeight}>
+            <div
+              style={{
+                padding: 16,
+                transform: `scale(${scale})`,
+              }}
+            >
+              <ErrorBoundary
+                componentName={componentName}
+                fallback={
+                  <Text size="xs" style={{ color: 'var(--color-danger)' }}>
+                    Error rendering variant
+                  </Text>
+                }
+              >
+                <FragmentRenderer variant={variant}>
+                  {(content, isLoading, error) => {
+                    if (isLoading) {
+                      return (
+                        <Stack align="center" justify="center" style={{ padding: 16 }}>
+                          <LoaderIndicator />
+                        </Stack>
+                      );
+                    }
+                    if (error) {
+                      return (
+                        <Text size="xs" style={{ color: 'var(--color-danger)', padding: 8 }}>
+                          {error.message}
+                        </Text>
+                      );
+                    }
+                    return content;
+                  }}
+                </FragmentRenderer>
+              </ErrorBoundary>
+            </div>
+          </ShadowPreview>
+        )}
+      </div>
+
+      {/* Tags/badges */}
+      {variant.hasPlayFunction && (
+        <div style={{ position: 'absolute', bottom: 8, right: 8, zIndex: 10 }}>
+          <Badge variant="info" size="sm">play</Badge>
+        </div>
+      )}
+    </div>
+  );
+}