@fragments-sdk/cli 0.10.1 → 0.12.1

package/src/viewer/hooks/useA11yService.ts

@@ -1,364 +0,0 @@
-/**
- * A11y Service Hook
- *
- * Central service for triggering accessibility scans with:
- * - Debouncing logic to prevent excessive scans during rapid changes
- * - Scan queue with concurrency limit
- * - Automatic re-scanning on HMR invalidation
- */
-
-import { useCallback, useEffect, useRef, useState } from 'react';
-import type {
-  A11yServiceConfig,
-  ComponentScanState,
-  ScanStatus,
-} from '../types/a11y.js';
-import {
-  updateComponentA11yResult,
-  getComponentA11yResult,
-  invalidateComponents,
-  isComponentStale,
-  getA11ySummary,
-} from './useA11yCache.js';
-import { runAxeScan, type ScanResult } from '../webmcp/scan-utils.js';
-
-// Default configuration
-const DEFAULT_CONFIG: A11yServiceConfig = {
-  hmrDebounceMs: 500,
-  navigationDebounceMs: 200,
-  scanCooldownMs: 1000,
-  maxConcurrentScans: 2,
-};
-
-// Global state for the service (singleton pattern)
-interface A11yServiceState {
-  activeScanCount: number;
-  scanQueue: Array<{
-    componentName: string;
-    targetSelector: string;
-    variant?: string;
-    resolve: (result: ScanResult | null) => void;
-    reject: (error: Error) => void;
-  }>;
-  debounceTimers: Map<string, NodeJS.Timeout>;
-  lastScanTimes: Map<string, number>;
-  componentStates: Map<string, ComponentScanState>;
-}
-
-const serviceState: A11yServiceState = {
-  activeScanCount: 0,
-  scanQueue: [],
-  debounceTimers: new Map(),
-  lastScanTimes: new Map(),
-  componentStates: new Map(),
-};
-
-/**
- * Process the scan queue
- */
-async function processQueue(config: A11yServiceConfig): Promise<void> {
-  while (
-    serviceState.scanQueue.length > 0 &&
-    serviceState.activeScanCount < config.maxConcurrentScans
-  ) {
-    const item = serviceState.scanQueue.shift();
-    if (!item) break;
-
-    serviceState.activeScanCount++;
-
-    // Update component state
-    serviceState.componentStates.set(item.componentName, {
-      status: 'scanning',
-      lastScanAt: Date.now(),
-    });
-
-    // Dispatch scanning event
-    window.dispatchEvent(new CustomEvent('a11y-scan-started', {
-      detail: { componentName: item.componentName },
-    }));
-
-    try {
-      const result = await runAxeScan(item.targetSelector);
-
-      if (result) {
-        // Update cache with full results
-        updateComponentA11yResult(item.componentName, {
-          violations: result.violations,
-          passes: result.passes,
-          incomplete: result.incomplete,
-          counts: result.counts,
-          variant: item.variant,
-        });
-
-        serviceState.componentStates.set(item.componentName, {
-          status: 'completed',
-          lastScanAt: Date.now(),
-        });
-      } else {
-        serviceState.componentStates.set(item.componentName, {
-          status: 'error',
-          error: 'Target element not found',
-        });
-      }
-
-      serviceState.lastScanTimes.set(item.componentName, Date.now());
-      item.resolve(result);
-    } catch (error) {
-      serviceState.componentStates.set(item.componentName, {
-        status: 'error',
-        error: error instanceof Error ? error.message : 'Scan failed',
-      });
-      item.reject(error instanceof Error ? error : new Error('Scan failed'));
-    } finally {
-      serviceState.activeScanCount--;
-
-      // Dispatch scan complete event
-      window.dispatchEvent(new CustomEvent('a11y-scan-completed', {
-        detail: { componentName: item.componentName },
-      }));
-
-      // Process next item in queue
-      processQueue(config);
-    }
-  }
-}
-
-/**
- * Options for the useA11yService hook
- */
-export interface UseA11yServiceOptions {
-  /** Override default configuration */
-  config?: Partial<A11yServiceConfig>;
-  /** Component name being scanned */
-  componentName?: string;
-  /** Target selector for scanning */
-  targetSelector?: string;
-  /** Current variant name */
-  variant?: string;
-  /** Auto-scan when component changes */
-  autoScan?: boolean;
-}
-
-/**
- * A11y Service Hook
- *
- * Provides methods for triggering and managing accessibility scans.
- */
-export function useA11yService(options: UseA11yServiceOptions = {}) {
-  const {
-    config: configOverrides = {},
-    componentName,
-    targetSelector = '[data-preview-container="true"]',
-    variant,
-    autoScan = true,
-  } = options;
-
-  const config: A11yServiceConfig = { ...DEFAULT_CONFIG, ...configOverrides };
-  const configRef = useRef(config);
-  configRef.current = config;
-
-  const [scanStatus, setScanStatus] = useState<ScanStatus>('idle');
-  const [lastResult, setLastResult] = useState<ScanResult | null>(null);
-
-  /**
-   * Queue a scan for a component
-   */
-  const scanComponent = useCallback(
-    (
-      targetComponentName: string = componentName || '',
-      targetSel: string = targetSelector,
-      targetVariant?: string
-    ): Promise<ScanResult | null> => {
-      if (!targetComponentName) {
-        return Promise.resolve(null);
-      }
-
-      // Check cooldown
-      const lastScan = serviceState.lastScanTimes.get(targetComponentName);
-      if (lastScan && Date.now() - lastScan < configRef.current.scanCooldownMs) {
-        // Return cached result if available
-        const cached = getComponentA11yResult(targetComponentName);
-        if (cached) {
-          return Promise.resolve({
-            violations: cached.violations,
-            passes: cached.passes,
-            incomplete: cached.incomplete,
-            counts: cached.counts,
-          });
-        }
-      }
-
-      return new Promise((resolve, reject) => {
-        serviceState.scanQueue.push({
-          componentName: targetComponentName,
-          targetSelector: targetSel,
-          variant: targetVariant || variant,
-          resolve,
-          reject,
-        });
-
-        serviceState.componentStates.set(targetComponentName, { status: 'pending' });
-        setScanStatus('pending');
-
-        // Start processing
-        processQueue(configRef.current);
-      });
-    },
-    [componentName, targetSelector, variant]
-  );
-
-  /**
-   * Scan with debouncing (for HMR or rapid changes)
-   */
-  const scanDebounced = useCallback(
-    (
-      debounceMs: number = configRef.current.hmrDebounceMs,
-      targetComponentName: string = componentName || ''
-    ) => {
-      if (!targetComponentName) return;
-
-      // Clear existing timer
-      const existingTimer = serviceState.debounceTimers.get(targetComponentName);
-      if (existingTimer) {
-        clearTimeout(existingTimer);
-      }
-
-      // Set new timer
-      const timer = setTimeout(() => {
-        serviceState.debounceTimers.delete(targetComponentName);
-        scanComponent(targetComponentName);
-      }, debounceMs);
-
-      serviceState.debounceTimers.set(targetComponentName, timer);
-    },
-    [componentName, scanComponent]
-  );
-
-  /**
-   * Invalidate cache for components and optionally trigger re-scan
-   */
-  const invalidate = useCallback(
-    (componentNames: string[], rescan: boolean = true) => {
-      invalidateComponents(componentNames);
-
-      if (rescan) {
-        // Debounce each component's re-scan
-        for (const name of componentNames) {
-          scanDebounced(configRef.current.hmrDebounceMs, name);
-        }
-      }
-    },
-    [scanDebounced]
-  );
-
-  /**
-   * Get current scan state for a component
-   */
-  const getComponentState = useCallback(
-    (name: string = componentName || ''): ComponentScanState => {
-      return serviceState.componentStates.get(name) || { status: 'idle' };
-    },
-    [componentName]
-  );
-
-  /**
-   * Check if a component needs re-scanning
-   */
-  const needsRescan = useCallback(
-    (name: string = componentName || ''): boolean => {
-      if (!name) return false;
-      return isComponentStale(name, config.scanCooldownMs);
-    },
-    [componentName, config.scanCooldownMs]
-  );
-
-  // Listen for HMR invalidation events
-  useEffect(() => {
-    const handleInvalidate = (event: CustomEvent<{ components: string[] }>) => {
-      const { components } = event.detail;
-
-      // If our component is in the list, trigger a debounced re-scan
-      if (componentName && components.includes(componentName)) {
-        setScanStatus('pending');
-        scanDebounced(configRef.current.hmrDebounceMs, componentName);
-      }
-    };
-
-    const handleScanStarted = (event: CustomEvent<{ componentName: string }>) => {
-      if (event.detail.componentName === componentName) {
-        setScanStatus('scanning');
-      }
-    };
-
-    const handleScanCompleted = (event: CustomEvent<{ componentName: string }>) => {
-      if (event.detail.componentName === componentName) {
-        setScanStatus('completed');
-        // Update last result from cache
-        const cached = getComponentA11yResult(componentName || '');
-        if (cached) {
-          setLastResult({
-            violations: cached.violations,
-            passes: cached.passes,
-            incomplete: cached.incomplete,
-            counts: cached.counts,
-          });
-        }
-      }
-    };
-
-    window.addEventListener('a11y-cache-invalidated', handleInvalidate as EventListener);
-    window.addEventListener('a11y-scan-started', handleScanStarted as EventListener);
-    window.addEventListener('a11y-scan-completed', handleScanCompleted as EventListener);
-
-    return () => {
-      window.removeEventListener('a11y-cache-invalidated', handleInvalidate as EventListener);
-      window.removeEventListener('a11y-scan-started', handleScanStarted as EventListener);
-      window.removeEventListener('a11y-scan-completed', handleScanCompleted as EventListener);
-    };
-  }, [componentName, scanDebounced]);
-
-  // Auto-scan when component name changes and cache is stale
-  useEffect(() => {
-    if (!autoScan || !componentName) return;
-
-    if (needsRescan(componentName)) {
-      scanDebounced(configRef.current.navigationDebounceMs, componentName);
-    } else {
-      // Load from cache
-      const cached = getComponentA11yResult(componentName);
-      if (cached) {
-        setLastResult({
-          violations: cached.violations,
-          passes: cached.passes,
-          incomplete: cached.incomplete,
-          counts: cached.counts,
-        });
-        setScanStatus('completed');
-      }
-    }
-  }, [autoScan, componentName, needsRescan, scanDebounced]);
-
-  return {
-    // Methods
-    scanComponent,
-    scanDebounced,
-    invalidate,
-    getComponentState,
-    needsRescan,
-    getSummary: getA11ySummary,
-
-    // State
-    scanStatus,
-    isScanning: scanStatus === 'scanning' || scanStatus === 'pending',
-    lastResult,
-  };
-}
-
-/**
- * Dispatch a11y invalidation event (for use from vite-plugin HMR)
- */
-export function dispatchA11yInvalidate(components: string[], file: string): void {
-  window.dispatchEvent(new CustomEvent('a11y-invalidate-hmr', {
-    detail: { components, file, timestamp: Date.now() },
-  }));
-}

package/src/viewer/hooks/useActions.ts

@@ -1,138 +0,0 @@
-/**
- * Actions logging hook - tracks callback invocations for debugging
- *
- * Similar to Storybook's Actions addon, this logs when callbacks like
- * onClick, onChange, etc. are invoked, showing the arguments passed.
- */
-
-import { useState, useCallback, useRef } from "react";
-
-export interface ActionLog {
-  id: string;
-  name: string;
-  args: unknown[];
-  timestamp: number;
-  count: number; // For repeated identical actions
-}
-
-export interface UseActionsReturn {
-  /** All logged actions */
-  logs: ActionLog[];
-  /** Add a new action log */
-  logAction: (name: string, args: unknown[]) => void;
-  /** Clear all logs */
-  clearLogs: () => void;
-  /** Wrap a callback to automatically log when called */
-  wrapCallback: <T extends (...args: unknown[]) => unknown>(
-    name: string,
-    callback?: T
-  ) => (...args: Parameters<T>) => ReturnType<T> | undefined;
-  /** Wrap multiple callbacks in an object */
-  wrapCallbacks: (
-    callbacks: Record<string, ((...args: unknown[]) => unknown) | undefined>
-  ) => Record<string, (...args: unknown[]) => unknown>;
-}
-
-const MAX_LOGS = 100;
-
-export function useActions(): UseActionsReturn {
-  const [logs, setLogs] = useState<ActionLog[]>([]);
-  const logIdCounter = useRef(0);
-
-  const logAction = useCallback((name: string, args: unknown[]) => {
-    setLogs((prevLogs) => {
-      // Check if the last log is the same action (for counting repeated calls)
-      const lastLog = prevLogs[0];
-      if (
-        lastLog &&
-        lastLog.name === name &&
-        JSON.stringify(lastLog.args) === JSON.stringify(args)
-      ) {
-        // Increment count on existing log
-        return [
-          { ...lastLog, count: lastLog.count + 1, timestamp: Date.now() },
-          ...prevLogs.slice(1),
-        ];
-      }
-
-      // Add new log
-      const newLog: ActionLog = {
-        id: `action-${++logIdCounter.current}`,
-        name,
-        args,
-        timestamp: Date.now(),
-        count: 1,
-      };
-
-      // Keep only the last MAX_LOGS entries
-      return [newLog, ...prevLogs].slice(0, MAX_LOGS);
-    });
-  }, []);
-
-  const clearLogs = useCallback(() => {
-    setLogs([]);
-  }, []);
-
-  const wrapCallback = useCallback(
-    <T extends (...args: unknown[]) => unknown>(name: string, callback?: T) => {
-      return (...args: Parameters<T>): ReturnType<T> | undefined => {
-        logAction(name, args);
-        if (callback) {
-          return callback(...args) as ReturnType<T>;
-        }
-        return undefined;
-      };
-    },
-    [logAction]
-  );
-
-  const wrapCallbacks = useCallback(
-    (callbacks: Record<string, ((...args: unknown[]) => unknown) | undefined>) => {
-      const wrapped: Record<string, (...args: unknown[]) => unknown> = {};
-      for (const [name, callback] of Object.entries(callbacks)) {
-        wrapped[name] = wrapCallback(name, callback);
-      }
-      return wrapped;
-    },
-    [wrapCallback]
-  );
-
-  return {
-    logs,
-    logAction,
-    clearLogs,
-    wrapCallback,
-    wrapCallbacks,
-  };
-}
-
-/**
- * Format a value for display in the actions panel
- */
-export function formatActionArg(value: unknown, maxLength = 100): string {
-  if (value === undefined) return "undefined";
-  if (value === null) return "null";
-  if (typeof value === "function") return "ƒ()";
-  if (typeof value === "symbol") return value.toString();
-
-  if (value instanceof Event) {
-    return `${value.constructor.name} { type: "${value.type}" }`;
-  }
-
-  if (value instanceof Element) {
-    const tag = value.tagName.toLowerCase();
-    const id = value.id ? `#${value.id}` : "";
-    const className = value.className ? `.${value.className.split(" ")[0]}` : "";
-    return `<${tag}${id}${className}>`;
-  }
-
-  try {
-    const str = JSON.stringify(value, null, 2);
-    if (str.length > maxLength) {
-      return str.slice(0, maxLength) + "...";
-    }
-    return str;
-  } catch {
-    return String(value);
-  }
-}

package/src/viewer/hooks/useAppState.ts

@@ -1,147 +0,0 @@
-/**
- * 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 = 'styles' | 'accessibility' | 'interactions' | 'graph' | 'performance';
-
-interface AppUIState {
-  activePanel: ActivePanel;
-  panelOpen: boolean;
-  showHealthDashboard: boolean;
-  showComparison: boolean;
-  showShortcutsHelp: boolean;
-  showMatrixView: boolean;
-  showCommandPalette: boolean;
-  showMultiViewport: boolean;
-  showAside: 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: 'TOGGLE_ASIDE' }
-  | { type: 'SET_ASIDE'; payload: boolean }
-  | { type: 'CLOSE_ALL_MODALS' };
-
-function getInitialAsideState(): boolean {
-  try {
-    const stored = localStorage.getItem('fragments-aside-visible');
-    if (stored !== null) return stored === 'true';
-  } catch { /* noop */ }
-  return true;
-}
-
-const initialState: AppUIState = {
-  activePanel: 'accessibility',
-  panelOpen: false,
-  showHealthDashboard: false,
-  showComparison: false,
-  showShortcutsHelp: false,
-  showMatrixView: false,
-  showCommandPalette: false,
-  showMultiViewport: false,
-  showAside: getInitialAsideState(),
-  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 'TOGGLE_ASIDE': {
-      const next = !state.showAside;
-      try { localStorage.setItem('fragments-aside-visible', String(next)); } catch { /* noop */ }
-      return { ...state, showAside: next };
-    }
-    case 'SET_ASIDE': {
-      try { localStorage.setItem('fragments-aside-visible', String(action.payload)); } catch { /* noop */ }
-      return { ...state, showAside: action.payload };
-    }
-    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' }),
-    toggleAside: () => dispatch({ type: 'TOGGLE_ASIDE' }),
-    setAside: (show: boolean) => dispatch({ type: 'SET_ASIDE', payload: show }),
-    closeAllModals: () => dispatch({ type: 'CLOSE_ALL_MODALS' }),
-  }), []);
-
-  return { state, actions };
-}
-
-export type { AppUIState, AppUIAction };

package/src/viewer/hooks/useCompiledFragments.ts

@@ -1,42 +0,0 @@
-import { useState, useEffect } from "react";
-import type { CompiledFragmentsFile } from "@fragments-sdk/context/types";
-
-interface UseCompiledFragmentsResult {
-  data: CompiledFragmentsFile | null;
-  loading: boolean;
-  error: string | null;
-}
-
-export function useCompiledFragments(): UseCompiledFragmentsResult {
-  const [data, setData] = useState<CompiledFragmentsFile | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    fetch("/fragments/compiled.json")
-      .then((res) => {
-        if (!res.ok) throw new Error(`HTTP ${res.status}`);
-        return res.json();
-      })
-      .then((json) => {
-        if (!cancelled) {
-          setData(json as CompiledFragmentsFile);
-          setLoading(false);
-        }
-      })
-      .catch((err) => {
-        if (!cancelled) {
-          setError(err instanceof Error ? err.message : String(err));
-          setLoading(false);
-        }
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, []);
-
-  return { data, loading, error };
-}