@fragments-sdk/viewer 0.2.1

package/src/components/ActionCapture.tsx

@@ -0,0 +1,172 @@
+/**
+ * ActionCapture component - captures DOM events for action logging.
+ *
+ * Uses event delegation to capture interactions at the DOM level,
+ * which works even when component render functions don't pass callbacks.
+ */
+
+import { useRef, useEffect, type ReactNode } from 'react';
+
+interface ActionCaptureProps {
+  children: ReactNode;
+  onAction: (name: string, args: unknown[]) => void;
+  enabled?: boolean;
+}
+
+// Events to capture
+const CAPTURE_EVENTS = [
+  'click',
+  'dblclick',
+  'change',
+  'input',
+  'submit',
+  'focus',
+  'blur',
+  'keydown',
+  'keyup',
+] as const;
+
+// Map event types to action names
+function getActionName(event: Event): string {
+  const type = event.type;
+  // Convert to React-style naming
+  switch (type) {
+    case 'click': return 'onClick';
+    case 'dblclick': return 'onDoubleClick';
+    case 'change': return 'onChange';
+    case 'input': return 'onInput';
+    case 'submit': return 'onSubmit';
+    case 'focus': return 'onFocus';
+    case 'blur': return 'onBlur';
+    case 'keydown': return 'onKeyDown';
+    case 'keyup': return 'onKeyUp';
+    default: return `on${type.charAt(0).toUpperCase() + type.slice(1)}`;
+  }
+}
+
+// Extract useful information about the target element
+function getElementInfo(element: Element): Record<string, unknown> {
+  const tag = element.tagName.toLowerCase();
+  const info: Record<string, unknown> = { element: tag };
+
+  // Get identifying attributes
+  if (element.id) info.id = element.id;
+  if (element.className && typeof element.className === 'string') {
+    const classes = element.className.trim().split(/\s+/).slice(0, 3);
+    if (classes.length > 0 && classes[0]) info.className = classes.join(' ');
+  }
+
+  // Get accessibility info
+  const role = element.getAttribute('role');
+  if (role) info.role = role;
+
+  const ariaLabel = element.getAttribute('aria-label');
+  if (ariaLabel) info['aria-label'] = ariaLabel;
+
+  // Get text content (truncated)
+  const text = element.textContent?.trim();
+  if (text && text.length > 0 && text.length <= 50) {
+    info.text = text;
+  } else if (text && text.length > 50) {
+    info.text = text.slice(0, 47) + '...';
+  }
+
+  // Get input-specific info
+  if (element instanceof HTMLInputElement) {
+    info.type = element.type;
+    info.name = element.name || undefined;
+    if (element.type === 'checkbox' || element.type === 'radio') {
+      info.checked = element.checked;
+    } else if (element.type !== 'password') {
+      info.value = element.value;
+    }
+  } else if (element instanceof HTMLSelectElement) {
+    info.name = element.name || undefined;
+    info.value = element.value;
+    info.selectedText = element.options[element.selectedIndex]?.text;
+  } else if (element instanceof HTMLTextAreaElement) {
+    info.name = element.name || undefined;
+    info.value = element.value.length > 100 ? element.value.slice(0, 97) + '...' : element.value;
+  } else if (element instanceof HTMLButtonElement) {
+    info.type = element.type;
+    if (element.name) info.name = element.name;
+  }
+
+  // Clean up undefined values
+  return Object.fromEntries(Object.entries(info).filter(([, v]) => v !== undefined));
+}
+
+// Extract keyboard event info
+function getKeyboardInfo(event: KeyboardEvent): Record<string, unknown> {
+  return {
+    key: event.key,
+    code: event.code,
+    ...(event.ctrlKey && { ctrlKey: true }),
+    ...(event.shiftKey && { shiftKey: true }),
+    ...(event.altKey && { altKey: true }),
+    ...(event.metaKey && { metaKey: true }),
+  };
+}
+
+export function ActionCapture({ children, onAction, enabled = true }: ActionCaptureProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const container = containerRef.current;
+    if (!container) return;
+
+    const handleEvent = (event: Event) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+
+      // Skip if the event is from the container itself
+      if (target === container) return;
+
+      // Get action name
+      const actionName = getActionName(event);
+
+      // Build args array with useful info
+      const args: unknown[] = [];
+
+      // Add element info
+      const elementInfo = getElementInfo(target);
+      args.push(elementInfo);
+
+      // Add keyboard-specific info for key events
+      if (event instanceof KeyboardEvent) {
+        args.push(getKeyboardInfo(event));
+      }
+
+      // Add mouse position for click events
+      if (event instanceof MouseEvent && (event.type === 'click' || event.type === 'dblclick')) {
+        args.push({
+          clientX: event.clientX,
+          clientY: event.clientY,
+          button: event.button,
+        });
+      }
+
+      onAction(actionName, args);
+    };
+
+    // Attach event listeners with capture phase
+    // This ensures we catch events even if stopPropagation is called
+    CAPTURE_EVENTS.forEach(eventType => {
+      container.addEventListener(eventType, handleEvent, { capture: true });
+    });
+
+    return () => {
+      CAPTURE_EVENTS.forEach(eventType => {
+        container.removeEventListener(eventType, handleEvent, { capture: true });
+      });
+    };
+  }, [onAction, enabled]);
+
+  return (
+    <div ref={containerRef} style={{ display: 'contents' }}>
+      {children}
+    </div>
+  );
+}

package/src/components/ActionsPanel.tsx

@@ -0,0 +1,332 @@
+/**
+ * Actions Panel - Storybook-style event logging
+ *
+ * Displays a log of callback invocations (onClick, onChange, etc.)
+ * with expandable argument details and timestamps.
+ */
+
+import { useState, useMemo } from "react";
+import type { ActionLog } from "../hooks/useActions.js";
+import { formatActionArg } from "../hooks/useActions.js";
+import { Button, Stack, Text, Badge, Input, Menu, Separator, Box } from "@fragments-sdk/ui";
+import {
+  TrashIcon,
+  ChevronDownIcon,
+  ChevronRightIcon,
+  PlayIcon,
+  ExportIcon,
+  DownloadIcon,
+  CopyIcon,
+  CheckIcon,
+} from "./Icons.js";
+import {
+  exportActions,
+  copyToClipboard,
+  downloadAsFile,
+  getFileExtension,
+  type ExportFormat,
+} from "../utils/actionExport.js";
+
+interface ActionsPanelProps {
+  /** List of action logs */
+  logs: ActionLog[];
+  /** Callback to clear all logs */
+  onClear: () => void;
+  /** Component name for export context */
+  componentName?: string;
+  /** Variant name for export context */
+  variantName?: string;
+}
+
+export function ActionsPanel({ logs, onClear, componentName = 'Component', variantName = 'Default' }: ActionsPanelProps) {
+  const [expandedLogs, setExpandedLogs] = useState<Set<string>>(new Set());
+  const [filter, setFilter] = useState("");
+  const [copyFeedback, setCopyFeedback] = useState<string | null>(null);
+
+  const filteredLogs = useMemo(() => {
+    if (!filter) return logs;
+    const lowerFilter = filter.toLowerCase();
+    return logs.filter((log) => log.name.toLowerCase().includes(lowerFilter));
+  }, [logs, filter]);
+
+  const toggleExpanded = (id: string) => {
+    setExpandedLogs((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) {
+        next.delete(id);
+      } else {
+        next.add(id);
+      }
+      return next;
+    });
+  };
+
+  const formatTime = (timestamp: number) => {
+    const date = new Date(timestamp);
+    return date.toLocaleTimeString("en-US", {
+      hour12: false,
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    });
+  };
+
+  const handleExport = async (format: ExportFormat, action: 'copy' | 'download') => {
+    const content = exportActions(logs, format, {
+      componentName,
+      variantName,
+      includeComments: true,
+    });
+
+    if (action === 'copy') {
+      const success = await copyToClipboard(content);
+      if (success) {
+        setCopyFeedback(format);
+        setTimeout(() => setCopyFeedback(null), 2000);
+      }
+    } else {
+      const filename = `${componentName}-${variantName}-actions${getFileExtension(format)}`;
+      downloadAsFile(content, filename.toLowerCase().replace(/\s+/g, '-'));
+    }
+  };
+
+  // No logs state
+  if (logs.length === 0) {
+    return (
+      <Stack style={{ height: '100%' }}>
+        <Box padding="md" borderBottom>
+          <Stack direction="row" align="center" gap="sm">
+            <PlayIcon style={{ width: 16, height: 16 }} />
+            <Text weight="medium">Actions</Text>
+          </Stack>
+        </Box>
+        <Stack align="center" justify="center" style={{ flex: 1, padding: '32px', textAlign: 'center' }}>
+          <div style={{ maxWidth: '28rem' }}>
+            <div style={{ width: '48px', height: '48px', borderRadius: '9999px', background: 'var(--bg-secondary)', display: 'flex', alignItems: 'center', justifyContent: 'center', margin: '0 auto 16px' }}>
+              <PlayIcon style={{ width: 24, height: 24, color: 'var(--text-tertiary)' }} />
+            </div>
+            <Text weight="medium" color="secondary" style={{ marginBottom: '8px' }}>
+              No actions logged yet
+            </Text>
+            <Text size="sm" color="tertiary">
+              Interact with the component to see callback invocations here.
+              Actions like <Box as="code" padding="xs" background="secondary" rounded="sm" style={{ fontSize: '12px', display: 'inline' }}>onClick</Box>, <Box as="code" padding="xs" background="secondary" rounded="sm" style={{ fontSize: '12px', display: 'inline' }}>onChange</Box>, etc. will be logged automatically.
+            </Text>
+          </div>
+        </Stack>
+      </Stack>
+    );
+  }
+
+  return (
+    <Stack style={{ height: '100%' }}>
+      {/* Header */}
+      <Box padding="sm" borderBottom>
+        <Stack direction="row" align="center" justify="between" gap="sm">
+          <Stack direction="row" align="center" gap="sm" style={{ flex: 1 }}>
+            <Stack direction="row" align="center" gap="sm">
+              <PlayIcon style={{ width: 16, height: 16 }} />
+              <Text weight="medium" size="sm">Actions</Text>
+            </Stack>
+            <Badge size="sm">{logs.length}</Badge>
+          </Stack>
+          <Stack direction="row" align="center" gap="sm">
+            <Input
+              size="sm"
+              placeholder="Filter..."
+              value={filter}
+              onChange={(e: React.ChangeEvent<HTMLInputElement>) => setFilter(e.target.value)}
+              style={{ width: '96px' }}
+            />
+
+            {/* Export dropdown */}
+            <Menu>
+              <Menu.Trigger>
+                <Button variant="ghost" size="sm" title="Export actions">
+                  <ExportIcon style={{ width: 16, height: 16 }} />
+                </Button>
+              </Menu.Trigger>
+              <Menu.Content>
+                <Box paddingX="sm" paddingY="xs">
+                  <Text size="xs" weight="medium" color="tertiary" style={{ textTransform: 'uppercase', letterSpacing: '0.05em' }}>
+                    Export as
+                  </Text>
+                </Box>
+
+                {/* JSON */}
+                <Stack direction="row" align="center" justify="between" style={{ padding: '6px 12px' }}>
+                  <Text size="sm" color="secondary">JSON</Text>
+                  <Stack direction="row" gap="xs">
+                    <Menu.Item onSelect={() => handleExport('json', 'copy')}>
+                      {copyFeedback === 'json' ? <CheckIcon style={{ width: 14, height: 14, color: '#22c55e' }} /> : <CopyIcon style={{ width: 14, height: 14 }} />}
+                    </Menu.Item>
+                    <Menu.Item onSelect={() => handleExport('json', 'download')}>
+                      <DownloadIcon style={{ width: 14, height: 14 }} />
+                    </Menu.Item>
+                  </Stack>
+                </Stack>
+
+                {/* Jest */}
+                <Stack direction="row" align="center" justify="between" style={{ padding: '6px 12px' }}>
+                  <Text size="sm" color="secondary">Jest Assertions</Text>
+                  <Stack direction="row" gap="xs">
+                    <Menu.Item onSelect={() => handleExport('jest', 'copy')}>
+                      {copyFeedback === 'jest' ? <CheckIcon style={{ width: 14, height: 14, color: '#22c55e' }} /> : <CopyIcon style={{ width: 14, height: 14 }} />}
+                    </Menu.Item>
+                    <Menu.Item onSelect={() => handleExport('jest', 'download')}>
+                      <DownloadIcon style={{ width: 14, height: 14 }} />
+                    </Menu.Item>
+                  </Stack>
+                </Stack>
+
+                {/* Playwright */}
+                <Stack direction="row" align="center" justify="between" style={{ padding: '6px 12px' }}>
+                  <Text size="sm" color="secondary">Playwright Test</Text>
+                  <Stack direction="row" gap="xs">
+                    <Menu.Item onSelect={() => handleExport('playwright', 'copy')}>
+                      {copyFeedback === 'playwright' ? <CheckIcon style={{ width: 14, height: 14, color: '#22c55e' }} /> : <CopyIcon style={{ width: 14, height: 14 }} />}
+                    </Menu.Item>
+                    <Menu.Item onSelect={() => handleExport('playwright', 'download')}>
+                      <DownloadIcon style={{ width: 14, height: 14 }} />
+                    </Menu.Item>
+                  </Stack>
+                </Stack>
+
+                <Separator />
+                <Box paddingX="sm" paddingY="xs">
+                  <Text size="xs" color="tertiary">
+                    {logs.length} action{logs.length !== 1 ? 's' : ''} recorded
+                  </Text>
+                </Box>
+              </Menu.Content>
+            </Menu>
+
+            <Button
+              onClick={onClear}
+              variant="ghost"
+              size="sm"
+              title="Clear all actions"
+            >
+              <TrashIcon style={{ width: 16, height: 16 }} />
+            </Button>
+          </Stack>
+        </Stack>
+      </Box>
+
+      {/* Log list */}
+      <Box overflow="auto" style={{ flex: 1 }}>
+        {filteredLogs.length === 0 ? (
+          <Box padding="md" style={{ textAlign: 'center' }}>
+            <Text size="sm" color="tertiary">No actions match "{filter}"</Text>
+          </Box>
+        ) : (
+          <div>
+            {filteredLogs.map((log, index) => (
+              <div key={log.id} style={{ borderBottom: index < filteredLogs.length - 1 ? '1px solid var(--border)' : undefined }}>
+                <ActionLogItem
+                  log={log}
+                  isExpanded={expandedLogs.has(log.id)}
+                  onToggle={() => toggleExpanded(log.id)}
+                  formatTime={formatTime}
+                />
+              </div>
+            ))}
+          </div>
+        )}
+      </Box>
+    </Stack>
+  );
+}
+
+interface ActionLogItemProps {
+  log: ActionLog;
+  isExpanded: boolean;
+  onToggle: () => void;
+  formatTime: (timestamp: number) => string;
+}
+
+function ActionLogItem({ log, isExpanded, onToggle, formatTime }: ActionLogItemProps) {
+  const [hovered, setHovered] = useState(false);
+  const hasArgs = log.args.length > 0;
+  const argsPreview = hasArgs
+    ? log.args.map((arg) => formatActionArg(arg, 50)).join(", ")
+    : "";
+
+  return (
+    <div
+      style={{ background: hovered ? 'var(--bg-secondary)' : 'transparent', transition: 'background 0.15s' }}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+    >
+      <button
+        onClick={onToggle}
+        disabled={!hasArgs}
+        style={{
+          width: '100%',
+          padding: '8px 12px',
+          display: 'flex',
+          alignItems: 'flex-start',
+          gap: '8px',
+          textAlign: 'left',
+          cursor: hasArgs ? 'pointer' : 'default',
+          border: 'none',
+          background: 'transparent',
+          color: 'inherit',
+        }}
+      >
+        {/* Expand icon */}
+        <div style={{ flexShrink: 0, width: '16px', height: '16px', marginTop: '2px' }}>
+          {hasArgs ? (
+            isExpanded ? (
+              <ChevronDownIcon style={{ width: 16, height: 16, color: 'var(--text-tertiary)' }} />
+            ) : (
+              <ChevronRightIcon style={{ width: 16, height: 16, color: 'var(--text-tertiary)' }} />
+            )
+          ) : (
+            <div style={{ width: '16px', height: '16px' }} />
+          )}
+        </div>
+
+        {/* Action name */}
+        <div style={{ flex: 1, minWidth: 0 }}>
+          <Stack direction="row" align="center" gap="sm">
+            <Text font="mono" size="sm" style={{ color: 'var(--color-accent)' }}>
+              {log.name}
+            </Text>
+            {log.count > 1 && (
+              <Badge size="sm">x{log.count}</Badge>
+            )}
+          </Stack>
+          {!isExpanded && hasArgs && (
+            <Text size="xs" color="tertiary" font="mono" style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', marginTop: '2px' }}>
+              ({argsPreview})
+            </Text>
+          )}
+        </div>
+
+        {/* Timestamp */}
+        <Text size="xs" color="tertiary" font="mono" style={{ flexShrink: 0 }}>
+          {formatTime(log.timestamp)}
+        </Text>
+      </button>
+
+      {/* Expanded args */}
+      {isExpanded && hasArgs && (
+        <div style={{ padding: '0 12px 12px 36px' }}>
+          <Box padding="sm" background="secondary" rounded="lg" overflow="auto">
+            {log.args.map((arg, index) => (
+              <div key={index} style={{ marginBottom: index < log.args.length - 1 ? '4px' : 0 }}>
+                <Text size="xs" color="tertiary" as="span">
+                  {log.args.length > 1 ? `[${index}] ` : ""}
+                </Text>
+                <pre style={{ display: 'inline', fontSize: '12px', fontFamily: 'monospace', color: 'var(--text-secondary)', whiteSpace: 'pre-wrap' }}>
+                  {formatActionArg(arg, 500)}
+                </pre>
+              </div>
+            ))}
+          </Box>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/AllVariantsPreview.tsx

@@ -0,0 +1,78 @@
+import type { ReactNode } from "react";
+import type { FragmentVariant } from '@fragments-sdk/core';
+import type { useViewSettings } from "../hooks/useViewSettings.js";
+import type { useTheme } from "./ThemeProvider.js";
+import { Stack } from "@fragments-sdk/ui";
+import { VariantPreviewCard } from "../shared/VariantPreviewCard";
+import { PreviewArea } from "./PreviewArea.js";
+import { resolveDisplayedCode } from "./CodePanel.js";
+import { getVariantSectionId } from "./viewer-utils.js";
+
+interface AllVariantsPreviewProps {
+  componentName: string;
+  fragmentPath: string;
+  variants: FragmentVariant[];
+  focusedVariantIndex: number;
+  zoom: ReturnType<typeof useViewSettings>["zoom"];
+  viewport: ReturnType<typeof useViewSettings>["viewport"];
+  customSize: ReturnType<typeof useViewSettings>["customSize"];
+  previewTheme: ReturnType<typeof useTheme>["resolvedTheme"];
+  showComparison: boolean;
+  allFigmaUrls: string[];
+  fallbackFigmaUrl?: string;
+  onRetry: () => void;
+  renderVariantContent: (variant: FragmentVariant) => ReactNode;
+  previewKeyBase: string;
+}
+
+export function AllVariantsPreview({
+  componentName,
+  fragmentPath,
+  variants,
+  focusedVariantIndex,
+  zoom,
+  viewport,
+  customSize,
+  previewTheme,
+  showComparison,
+  allFigmaUrls,
+  fallbackFigmaUrl,
+  onRetry,
+  renderVariantContent,
+  previewKeyBase,
+}: AllVariantsPreviewProps) {
+  return (
+    <Stack gap="lg" style={{ padding: "20px" }}>
+      {variants.map((variant, index) => (
+        <VariantPreviewCard
+          key={variant.name}
+          name={variant.name}
+          description={variant.description}
+          code={resolveDisplayedCode(componentName, variant)}
+          id={getVariantSectionId(componentName, variant.name)}
+          highlight={index === focusedVariantIndex}
+        >
+          <PreviewArea
+            componentName={componentName}
+            fragmentPath={fragmentPath}
+            variant={variant}
+            variants={variants}
+            zoom={zoom}
+            viewport={viewport}
+            customSize={customSize}
+            previewTheme={previewTheme}
+            showMatrixView={false}
+            showMultiViewport={false}
+            showComparison={showComparison}
+            figmaUrl={variant.figma || fallbackFigmaUrl}
+            allFigmaUrls={allFigmaUrls}
+            onSelectVariant={() => {}}
+            onRetry={onRetry}
+            renderContent={() => renderVariantContent(variant)}
+            previewKey={`${previewKeyBase}-${index}`}
+          />
+        </VariantPreviewCard>
+      ))}
+    </Stack>
+  );
+}