@fragments-sdk/cli 0.2.2

package/src/viewer/hooks/useAppState.ts

@@ -0,0 +1,124 @@
+/**
+ * Centralized UI state management for the App component.
+ * Uses useReducer for predictable state updates and better performance.
+ */
+
+import { useReducer, useCallback, useMemo } from 'react';
+
+export type ActivePanel = 'code' | 'styles' | 'accessibility' | 'interactions' | 'actions' | 'graph' | 'contract';
+
+interface AppUIState {
+  activePanel: ActivePanel;
+  panelOpen: boolean;
+  showHealthDashboard: boolean;
+  showComparison: boolean;
+  showShortcutsHelp: boolean;
+  showMatrixView: boolean;
+  showCommandPalette: boolean;
+  showMultiViewport: boolean;
+  linkCopied: boolean;
+  previewKey: number;
+}
+
+type AppUIAction =
+  | { type: 'SET_ACTIVE_PANEL'; payload: ActivePanel }
+  | { type: 'TOGGLE_PANEL' }
+  | { type: 'SET_PANEL_OPEN'; payload: boolean }
+  | { type: 'SET_HEALTH_DASHBOARD'; payload: boolean }
+  | { type: 'TOGGLE_COMPARISON' }
+  | { type: 'SET_COMPARISON'; payload: boolean }
+  | { type: 'TOGGLE_SHORTCUTS_HELP' }
+  | { type: 'SET_SHORTCUTS_HELP'; payload: boolean }
+  | { type: 'SET_MATRIX_VIEW'; payload: boolean }
+  | { type: 'SET_COMMAND_PALETTE'; payload: boolean }
+  | { type: 'SET_MULTI_VIEWPORT'; payload: boolean }
+  | { type: 'SET_LINK_COPIED'; payload: boolean }
+  | { type: 'INCREMENT_PREVIEW_KEY' }
+  | { type: 'CLOSE_ALL_MODALS' };
+
+const initialState: AppUIState = {
+  activePanel: 'code',
+  panelOpen: true,
+  showHealthDashboard: false,
+  showComparison: true,
+  showShortcutsHelp: false,
+  showMatrixView: false,
+  showCommandPalette: false,
+  showMultiViewport: false,
+  linkCopied: false,
+  previewKey: 0,
+};
+
+function appUIReducer(state: AppUIState, action: AppUIAction): AppUIState {
+  switch (action.type) {
+    case 'SET_ACTIVE_PANEL':
+      return { ...state, activePanel: action.payload };
+    case 'TOGGLE_PANEL':
+      return { ...state, panelOpen: !state.panelOpen };
+    case 'SET_PANEL_OPEN':
+      return { ...state, panelOpen: action.payload };
+    case 'SET_HEALTH_DASHBOARD':
+      return { ...state, showHealthDashboard: action.payload };
+    case 'TOGGLE_COMPARISON':
+      return { ...state, showComparison: !state.showComparison };
+    case 'SET_COMPARISON':
+      return { ...state, showComparison: action.payload };
+    case 'TOGGLE_SHORTCUTS_HELP':
+      return { ...state, showShortcutsHelp: !state.showShortcutsHelp };
+    case 'SET_SHORTCUTS_HELP':
+      return { ...state, showShortcutsHelp: action.payload };
+    case 'SET_MATRIX_VIEW':
+      // When enabling matrix view, disable multi-viewport
+      return {
+        ...state,
+        showMatrixView: action.payload,
+        showMultiViewport: action.payload ? false : state.showMultiViewport,
+      };
+    case 'SET_COMMAND_PALETTE':
+      return { ...state, showCommandPalette: action.payload };
+    case 'SET_MULTI_VIEWPORT':
+      // When enabling multi-viewport, disable matrix view
+      return {
+        ...state,
+        showMultiViewport: action.payload,
+        showMatrixView: action.payload ? false : state.showMatrixView,
+      };
+    case 'SET_LINK_COPIED':
+      return { ...state, linkCopied: action.payload };
+    case 'INCREMENT_PREVIEW_KEY':
+      return { ...state, previewKey: state.previewKey + 1 };
+    case 'CLOSE_ALL_MODALS':
+      return {
+        ...state,
+        showShortcutsHelp: false,
+        showCommandPalette: false,
+      };
+    default:
+      return state;
+  }
+}
+
+export function useAppState() {
+  const [state, dispatch] = useReducer(appUIReducer, initialState);
+
+  const actions = useMemo(() => ({
+    setActivePanel: (panel: ActivePanel) => dispatch({ type: 'SET_ACTIVE_PANEL', payload: panel }),
+    togglePanel: () => dispatch({ type: 'TOGGLE_PANEL' }),
+    setPanelOpen: (open: boolean) => dispatch({ type: 'SET_PANEL_OPEN', payload: open }),
+    setHealthDashboard: (show: boolean) => dispatch({ type: 'SET_HEALTH_DASHBOARD', payload: show }),
+    toggleComparison: () => dispatch({ type: 'TOGGLE_COMPARISON' }),
+    setComparison: (show: boolean) => dispatch({ type: 'SET_COMPARISON', payload: show }),
+    toggleShortcutsHelp: () => dispatch({ type: 'TOGGLE_SHORTCUTS_HELP' }),
+    setShortcutsHelp: (show: boolean) => dispatch({ type: 'SET_SHORTCUTS_HELP', payload: show }),
+    setMatrixView: (show: boolean) => dispatch({ type: 'SET_MATRIX_VIEW', payload: show }),
+    setCommandPalette: (show: boolean) => dispatch({ type: 'SET_COMMAND_PALETTE', payload: show }),
+    setMultiViewport: (show: boolean) => dispatch({ type: 'SET_MULTI_VIEWPORT', payload: show }),
+    setLinkCopied: (copied: boolean) => dispatch({ type: 'SET_LINK_COPIED', payload: copied }),
+    incrementPreviewKey: () => dispatch({ type: 'INCREMENT_PREVIEW_KEY' }),
+    closeAllModals: () => dispatch({ type: 'CLOSE_ALL_MODALS' }),
+  }), []);
+
+  return { state, actions };
+}
+
+export type { AppUIState, AppUIAction };

package/src/viewer/hooks/useFigmaIntegration.ts

@@ -0,0 +1,132 @@
+/**
+ * Figma integration hook.
+ * Handles fetching Figma styles and extracting rendered component styles.
+ */
+
+import { useState, useCallback, useEffect } from 'react';
+
+interface FigmaStylesState {
+  status: 'idle' | 'loading' | 'success' | 'error';
+  styles?: Record<string, string>;
+  error?: string;
+}
+
+interface UseFigmaIntegrationOptions {
+  figmaUrl?: string;
+  showComparison?: boolean;
+  dependencies?: unknown[]; // Dependencies that should reset styles when changed
+}
+
+export function useFigmaIntegration(options: UseFigmaIntegrationOptions = {}) {
+  const { figmaUrl, showComparison = false, dependencies = [] } = options;
+
+  const [figmaStyles, setFigmaStyles] = useState<FigmaStylesState>({ status: 'idle' });
+  const [renderedStyles, setRenderedStyles] = useState<Record<string, string> | null>(null);
+
+  // Fetch Figma styles from API
+  const fetchFigmaStyles = useCallback(async () => {
+    if (!figmaUrl) return;
+
+    setFigmaStyles({ status: 'loading' });
+
+    try {
+      const response = await fetch('/segments/figma-styles', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ figmaUrl }),
+      });
+
+      const result = await response.json();
+
+      if (result.error) {
+        setFigmaStyles({ status: 'error', error: result.error });
+      } else {
+        setFigmaStyles({ status: 'success', styles: result.styles });
+      }
+    } catch {
+      setFigmaStyles({ status: 'error', error: 'Failed to fetch Figma styles' });
+    }
+  }, [figmaUrl]);
+
+  // Extract computed styles from rendered component
+  const extractRenderedStyles = useCallback(() => {
+    const container = document.querySelector('[data-preview-container="true"]');
+    if (!container) return;
+
+    const candidates = container.querySelectorAll('*');
+    let bestElement: HTMLElement | null = null;
+    let bestScore = -1;
+
+    const isVisibleColor = (color: string | undefined): boolean => {
+      if (!color) return false;
+      if (color === 'transparent' || color === 'rgba(0, 0, 0, 0)') return false;
+      return true;
+    };
+
+    for (const el of candidates) {
+      const htmlEl = el as HTMLElement;
+      const styles = window.getComputedStyle(htmlEl);
+      let score = 0;
+
+      if (isVisibleColor(styles.backgroundColor)) score += 10;
+      if (styles.borderWidth && styles.borderWidth !== '0px') score += 3;
+      if (styles.boxShadow && styles.boxShadow !== 'none') score += 3;
+
+      const tagName = htmlEl.tagName.toLowerCase();
+      if (['button', 'a', 'input', 'select', 'textarea'].includes(tagName)) score += 5;
+      if (htmlEl.getAttribute('role') === 'button') score += 5;
+
+      const rect = htmlEl.getBoundingClientRect();
+      if (rect.width < 10 || rect.height < 10) score -= 10;
+      if (rect.width > 500 || rect.height > 500) score -= 3;
+
+      if (score > bestScore) {
+        bestScore = score;
+        bestElement = htmlEl;
+      }
+    }
+
+    if (!bestElement) return;
+
+    const styles = window.getComputedStyle(bestElement);
+    const relevantProps = [
+      'backgroundColor', 'borderColor', 'borderWidth', 'borderRadius',
+      'fontFamily', 'fontSize', 'fontWeight', 'lineHeight', 'letterSpacing',
+      'textAlign', 'boxShadow', 'padding', 'gap', 'opacity'
+    ];
+
+    const result: Record<string, string> = {};
+    for (const prop of relevantProps) {
+      const cssKey = prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+      const value = styles.getPropertyValue(cssKey);
+      if (value) result[prop] = value;
+    }
+
+    setRenderedStyles(result);
+  }, []);
+
+  // Reset styles when dependencies change
+  useEffect(() => {
+    setFigmaStyles({ status: 'idle' });
+    setRenderedStyles(null);
+  }, dependencies);
+
+  // Auto-fetch Figma styles when comparison is shown
+  useEffect(() => {
+    if (showComparison && figmaUrl && figmaStyles.status === 'idle') {
+      fetchFigmaStyles();
+    }
+  }, [showComparison, figmaUrl, figmaStyles.status, fetchFigmaStyles]);
+
+  return {
+    figmaStyles,
+    renderedStyles,
+    fetchFigmaStyles,
+    extractRenderedStyles,
+    isLoading: figmaStyles.status === 'loading',
+    hasError: figmaStyles.status === 'error',
+    errorMessage: figmaStyles.error,
+  };
+}
+
+export type { FigmaStylesState };

package/src/viewer/hooks/useHmrStatus.ts

@@ -0,0 +1,109 @@
+import { useState, useEffect, useCallback } from 'react';
+import type { HmrStatus } from '../constants/ui.js';
+
+/**
+ * Hook to track Vite HMR connection status.
+ * Returns the current connection status and any recent file changes.
+ */
+export function useHmrStatus() {
+  const [status, setStatus] = useState<HmrStatus>('connected');
+  const [lastUpdate, setLastUpdate] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Check if we're in a Vite environment
+    if (typeof import.meta.hot === 'undefined') {
+      return;
+    }
+
+    const hot = import.meta.hot;
+
+    // Listen for HMR connection status
+    // Vite emits these events on the WebSocket connection
+    const handleConnect = () => {
+      setStatus('connected');
+    };
+
+    const handleDisconnect = () => {
+      setStatus('disconnected');
+    };
+
+    const handleReconnecting = () => {
+      setStatus('reconnecting');
+    };
+
+    // Listen for module updates
+    const handleUpdate = (data: { type: string; path?: string }) => {
+      if (data.path) {
+        setLastUpdate(data.path);
+        // Clear the update notification after 3 seconds
+        setTimeout(() => setLastUpdate(null), 3000);
+      }
+    };
+
+    // Vite's HMR API
+    // @ts-expect-error Vite internal events
+    hot.on('vite:beforeUpdate', handleUpdate);
+
+    // Listen for WebSocket events via custom events
+    // These are dispatched by Vite's client
+    window.addEventListener('vite:ws-connect', handleConnect);
+    window.addEventListener('vite:ws-disconnect', handleDisconnect);
+
+    // For Vite 5+, we can use the connection status directly
+    // Check current status
+    try {
+      // @ts-expect-error Vite internal
+      if (hot.connection?.socket?.readyState === 1) {
+        setStatus('connected');
+      }
+    } catch {
+      // Ignore - may not be available
+    }
+
+    return () => {
+      window.removeEventListener('vite:ws-connect', handleConnect);
+      window.removeEventListener('vite:ws-disconnect', handleDisconnect);
+    };
+  }, []);
+
+  // Manual check for connection status every 5 seconds
+  useEffect(() => {
+    const checkConnection = () => {
+      if (typeof import.meta.hot === 'undefined') {
+        setStatus('disconnected');
+        return;
+      }
+
+      try {
+        // @ts-expect-error Vite internal
+        const socket = import.meta.hot.connection?.socket;
+        if (socket) {
+          switch (socket.readyState) {
+            case 0: // CONNECTING
+              setStatus('reconnecting');
+              break;
+            case 1: // OPEN
+              setStatus('connected');
+              break;
+            case 2: // CLOSING
+            case 3: // CLOSED
+              setStatus('disconnected');
+              break;
+          }
+        }
+      } catch {
+        // Ignore errors - HMR may not be available
+      }
+    };
+
+    // Initial check
+    checkConnection();
+
+    // Periodic check
+    const interval = setInterval(checkConnection, 5000);
+
+    return () => clearInterval(interval);
+  }, []);
+
+  return { status, lastUpdate };
+}

package/src/viewer/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,222 @@
+/**
+ * Keyboard Shortcuts Hook
+ *
+ * Provides global keyboard navigation for the viewer:
+ * - j/k or ↓/↑: Navigate components
+ * - [/] or ←/→: Navigate variants
+ * - 1-9: Jump to variant by number
+ * - t: Toggle preview theme
+ * - p: Toggle panel
+ * - cmd+shift+c: Copy link
+ * - ?: Show shortcuts help
+ * - Escape: Close modals/clear search
+ */
+
+import { useEffect, useCallback } from "react";
+
+export interface ShortcutActions {
+  /** Navigate to next component */
+  nextComponent: () => void;
+  /** Navigate to previous component */
+  prevComponent: () => void;
+  /** Navigate to next variant */
+  nextVariant: () => void;
+  /** Navigate to previous variant */
+  prevVariant: () => void;
+  /** Jump to variant by index (0-based) */
+  goToVariant: (index: number) => void;
+  /** Toggle preview theme */
+  toggleTheme: () => void;
+  /** Toggle panel open/closed */
+  togglePanel: () => void;
+  /** Copy shareable link */
+  copyLink: () => void;
+  /** Show shortcuts help */
+  showHelp: () => void;
+  /** Open search/command palette */
+  openSearch: () => void;
+  /** Close any open modal/dialog */
+  escape: () => void;
+}
+
+export interface ShortcutConfig {
+  /** Whether shortcuts are enabled */
+  enabled?: boolean;
+  /** Number of variants available */
+  variantCount?: number;
+}
+
+/**
+ * Check if an element is an input that should capture keyboard events
+ */
+function isInputElement(element: EventTarget | null): boolean {
+  if (!element || !(element instanceof HTMLElement)) return false;
+
+  const tagName = element.tagName.toLowerCase();
+  if (tagName === "input" || tagName === "textarea" || tagName === "select") {
+    return true;
+  }
+
+  if (element.isContentEditable) {
+    return true;
+  }
+
+  // Check if inside Monaco Editor
+  if (element.closest('.monaco-editor')) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Hook to register keyboard shortcuts
+ */
+export function useKeyboardShortcuts(
+  actions: Partial<ShortcutActions>,
+  config: ShortcutConfig = {}
+) {
+  const { enabled = true, variantCount = 0 } = config;
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!enabled) return;
+
+      // Don't capture events from input elements (except for specific shortcuts)
+      const isInput = isInputElement(event.target);
+
+      // Global shortcuts that work even in inputs
+      if (event.key === "Escape") {
+        actions.escape?.();
+        return;
+      }
+
+      // cmd+shift+c: Copy link (works everywhere)
+      if ((event.metaKey || event.ctrlKey) && event.shiftKey && event.key === "c") {
+        event.preventDefault();
+        actions.copyLink?.();
+        return;
+      }
+
+      // cmd+k: Open search/command palette (works everywhere)
+      if ((event.metaKey || event.ctrlKey) && event.key === "k") {
+        event.preventDefault();
+        actions.openSearch?.();
+        return;
+      }
+
+      // Skip other shortcuts if in input
+      if (isInput) return;
+
+      // "/" also opens search (when not in input)
+      if (event.key === "/") {
+        event.preventDefault();
+        actions.openSearch?.();
+        return;
+      }
+
+      // Navigation shortcuts
+      switch (event.key) {
+        // Component navigation
+        case "j":
+        case "ArrowDown":
+          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+            event.preventDefault();
+            actions.nextComponent?.();
+          }
+          break;
+
+        case "k":
+        case "ArrowUp":
+          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+            event.preventDefault();
+            actions.prevComponent?.();
+          }
+          break;
+
+        // Variant navigation
+        case "[":
+        case "ArrowLeft":
+          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+            event.preventDefault();
+            actions.prevVariant?.();
+          }
+          break;
+
+        case "]":
+        case "ArrowRight":
+          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+            event.preventDefault();
+            actions.nextVariant?.();
+          }
+          break;
+
+        // Number keys 1-9 for variant selection
+        case "1":
+        case "2":
+        case "3":
+        case "4":
+        case "5":
+        case "6":
+        case "7":
+        case "8":
+        case "9":
+          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+            const index = parseInt(event.key, 10) - 1;
+            if (index < variantCount) {
+              event.preventDefault();
+              actions.goToVariant?.(index);
+            }
+          }
+          break;
+
+        // Theme toggle
+        case "t":
+          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+            event.preventDefault();
+            actions.toggleTheme?.();
+          }
+          break;
+
+        // Panel toggle
+        case "p":
+          if (!event.metaKey && !event.ctrlKey && !event.altKey) {
+            event.preventDefault();
+            actions.togglePanel?.();
+          }
+          break;
+
+        // Help
+        case "?":
+          event.preventDefault();
+          actions.showHelp?.();
+          break;
+      }
+    },
+    [enabled, actions, variantCount]
+  );
+
+  useEffect(() => {
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [handleKeyDown]);
+}
+
+/**
+ * Keyboard shortcuts data for help display
+ */
+export const SHORTCUTS = [
+  { keys: ["j", "↓"], description: "Next component" },
+  { keys: ["k", "↑"], description: "Previous component" },
+  { keys: ["[", "←"], description: "Previous variant" },
+  { keys: ["]", "→"], description: "Next variant" },
+  { keys: ["1-9"], description: "Go to variant" },
+  { keys: ["t"], description: "Toggle preview theme" },
+  { keys: ["p"], description: "Toggle panel" },
+  { keys: ["⌘⇧C"], description: "Copy link" },
+  { keys: ["/", "⌘K"], description: "Search" },
+  { keys: ["?"], description: "Show shortcuts" },
+  { keys: ["Esc"], description: "Close / Clear" },
+];
+
+export default useKeyboardShortcuts;