@fragments-sdk/cli 0.2.2

package/src/viewer/hooks/useA11yService.ts

@@ -0,0 +1,498 @@
+/**
+ * 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 { Result } from 'axe-core';
+import type {
+  A11yServiceConfig,
+  SerializedViolation,
+  ComponentScanState,
+  ScanStatus,
+} from '../types/a11y.js';
+import {
+  updateComponentA11yResult,
+  getComponentA11yResult,
+  invalidateComponents,
+  isComponentStale,
+  getA11ySummary,
+} from './useA11yCache.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(),
+};
+
+// Cache the axe-core module
+let axeModule: typeof import('axe-core') | null = null;
+
+export interface ScanResult {
+  violations: SerializedViolation[];
+  passes: number;
+  incomplete: number;
+  counts: {
+    critical: number;
+    serious: number;
+    moderate: number;
+    minor: number;
+  };
+}
+
+/**
+ * Convert axe-core Result to SerializedViolation
+ */
+function serializeViolation(result: Result): SerializedViolation {
+  return {
+    id: result.id,
+    impact: result.impact || null,
+    description: result.description,
+    help: result.help,
+    helpUrl: result.helpUrl,
+    tags: result.tags,
+    nodes: result.nodes.map(node => ({
+      html: node.html,
+      target: node.target as string[],
+      failureSummary: node.failureSummary,
+      any: node.any?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+      all: node.all?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+      none: node.none?.map(check => ({
+        id: check.id,
+        data: check.data,
+        relatedNodes: check.relatedNodes?.map(rn => ({
+          html: rn.html,
+          target: rn.target as string[],
+        })),
+        impact: check.impact,
+        message: check.message,
+      })),
+    })),
+  };
+}
+
+/**
+ * Run axe-core scan on a target element
+ */
+async function runAxeScan(targetSelector: string): Promise<ScanResult | null> {
+  // Load axe-core if not cached
+  if (!axeModule) {
+    axeModule = await import('axe-core');
+  }
+  // Handle both ESM default export and CommonJS module
+  const axe = (axeModule as { default?: typeof import('axe-core') }).default || axeModule;
+
+  const target = document.querySelector(targetSelector);
+  if (!target) {
+    console.warn(`[A11y] Target element not found: ${targetSelector}`);
+    return null;
+  }
+
+  // Configure axe-core
+  axe.configure({
+    rules: [
+      { id: 'color-contrast', enabled: true },
+      { id: 'image-alt', enabled: true },
+      { id: 'button-name', enabled: true },
+      { id: 'link-name', enabled: true },
+      { id: 'label', enabled: true },
+      { id: 'aria-valid-attr', enabled: true },
+      { id: 'aria-valid-attr-value', enabled: true },
+    ],
+  });
+
+  // Run the scan
+  const results = await axe.run(target as HTMLElement, {
+    resultTypes: ['violations', 'passes', 'incomplete', 'inapplicable'],
+  });
+
+  // Count violations by severity
+  const counts = {
+    critical: 0,
+    serious: 0,
+    moderate: 0,
+    minor: 0,
+  };
+
+  for (const violation of results.violations) {
+    switch (violation.impact) {
+      case 'critical':
+        counts.critical++;
+        break;
+      case 'serious':
+        counts.serious++;
+        break;
+      case 'moderate':
+        counts.moderate++;
+        break;
+      case 'minor':
+      default:
+        counts.minor++;
+        break;
+    }
+  }
+
+  return {
+    violations: results.violations.map(serializeViolation),
+    passes: results.passes.length,
+    incomplete: results.incomplete.length,
+    counts,
+  };
+}
+
+/**
+ * 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

@@ -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);
+  }
+}