@fragments-sdk/viewer 0.2.1

package/src/hooks/useA11yService.ts

@@ -0,0 +1,364 @@
+/**
+ * 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/hooks/useActions.ts

@@ -0,0 +1,138 @@
+/**
+ * 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/hooks/useAppState.ts

@@ -0,0 +1,147 @@
+/**
+ * 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/hooks/useCompiledFragments.ts

@@ -0,0 +1,42 @@
+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 };
+}