@fragments-sdk/cli 0.2.2

package/src/viewer/entry.tsx

@@ -0,0 +1,299 @@
+import { createRoot, type Root } from "react-dom/client";
+import { Component, type ReactNode, type ErrorInfo } from "react";
+import { App } from "./components/App.js";
+import { ThemeProvider } from "./components/ThemeProvider.js";
+import { AppSkeleton } from "./components/SkeletonLoader.js";
+// Viewer shell styles - independent from UI library
+// UI library styles are only loaded in the isolated preview area
+import "./styles/globals.css";
+
+// App-level error boundary that catches any unhandled errors
+class AppErrorBoundary extends Component<{ children: ReactNode }, { hasError: boolean; error: Error | null; errorInfo: ErrorInfo | null }> {
+  constructor(props: { children: ReactNode }) {
+    super(props);
+    this.state = { hasError: false, error: null, errorInfo: null };
+  }
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error('[Fragments] App Error:', error);
+    console.error('[Fragments] Component Stack:', errorInfo.componentStack);
+    this.setState({ errorInfo });
+  }
+
+  handleRetry = () => {
+    this.setState({ hasError: false, error: null, errorInfo: null });
+    window.location.reload();
+  };
+
+  render() {
+    if (this.state.hasError) {
+      const { error, errorInfo } = this.state;
+      return (
+        <div style={{
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+          padding: '40px',
+          maxWidth: '800px',
+          margin: '0 auto',
+        }}>
+          <div style={{
+            background: '#fef2f2',
+            border: '1px solid #fecaca',
+            borderRadius: '12px',
+            padding: '24px',
+          }}>
+            <h1 style={{ color: '#dc2626', marginBottom: '16px', fontSize: '20px', fontWeight: 600 }}>
+              Application Error
+            </h1>
+            <p style={{ color: '#991b1b', marginBottom: '16px', fontSize: '14px' }}>
+              An error occurred while rendering the application:
+            </p>
+            <pre style={{
+              background: '#fee2e2',
+              border: '1px solid #fecaca',
+              borderRadius: '8px',
+              padding: '16px',
+              overflow: 'auto',
+              whiteSpace: 'pre-wrap',
+              wordBreak: 'break-word',
+              color: '#991b1b',
+              fontSize: '13px',
+              fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+              marginBottom: '16px',
+            }}>
+              {error?.message || 'Unknown error'}
+            </pre>
+            {errorInfo?.componentStack && (
+              <details style={{ marginBottom: '16px' }}>
+                <summary style={{
+                  color: '#b91c1c',
+                  cursor: 'pointer',
+                  fontSize: '13px',
+                  marginBottom: '8px',
+                }}>
+                  Show component stack trace
+                </summary>
+                <pre style={{
+                  background: '#fee2e2',
+                  border: '1px solid #fecaca',
+                  borderRadius: '8px',
+                  padding: '12px',
+                  overflow: 'auto',
+                  whiteSpace: 'pre-wrap',
+                  wordBreak: 'break-word',
+                  color: '#7f1d1d',
+                  fontSize: '11px',
+                  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+                  maxHeight: '300px',
+                }}>
+                  {error?.stack || errorInfo.componentStack}
+                </pre>
+              </details>
+            )}
+            <button
+              onClick={this.handleRetry}
+              style={{
+                background: '#dc2626',
+                color: 'white',
+                border: 'none',
+                borderRadius: '6px',
+                padding: '10px 16px',
+                fontSize: '14px',
+                fontWeight: 500,
+                cursor: 'pointer',
+              }}
+            >
+              Reload Application
+            </button>
+          </div>
+          <p style={{ marginTop: '16px', color: '#6b7280', fontSize: '13px' }}>
+            Check the browser console for more details. Common causes:
+          </p>
+          <ul style={{ color: '#6b7280', marginTop: '8px', paddingLeft: '20px', fontSize: '13px' }}>
+            <li>Syntax errors in segment or component files</li>
+            <li>Missing or undefined imports</li>
+            <li>Components that crash during render</li>
+            <li>Invalid props passed to components</li>
+          </ul>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+// Declare global types
+declare global {
+  interface Window {
+    __SEGMENTS__?: Array<{
+      path: string;
+      segment: import("../core/index.js").SegmentDefinition;
+    }>;
+    __SEGMENTS_CONFIG__?: import("../core/index.js").SegmentsConfig;
+    __SEGMENTS_ERROR__?: string;
+  }
+}
+
+type SegmentItem = {
+  path: string;
+  segment: import("../core/index.js").SegmentDefinition;
+};
+
+// Initialize segments from window or empty array
+let segments: SegmentItem[] = window.__SEGMENTS__ ?? [];
+let loadError: string | null = window.__SEGMENTS_ERROR__ ?? null;
+let appRoot: Root | null = null;
+
+// Filter helper
+function filterValidSegments(items: SegmentItem[]): SegmentItem[] {
+  return items.filter(s => s && s.segment && s.segment.meta);
+}
+
+// Async loader for virtual module (runs after initial render)
+async function loadSegmentsFromVirtualModule(): Promise<void> {
+  if (segments.length > 0 || loadError) {
+    // Already have segments or error from window
+    return;
+  }
+
+  try {
+    // @ts-expect-error Virtual module
+    const virtualModule = await import("virtual:fragments");
+    // Wait for lazy-loaded segments
+    if (virtualModule.segmentsPromise) {
+      segments = await virtualModule.segmentsPromise;
+    } else {
+      segments = virtualModule.segments;
+    }
+    segments = filterValidSegments(segments);
+  } catch (e) {
+    const error = e as Error;
+    loadError = error.message || "Failed to load segments";
+    console.error("[Fragments] Failed to load:", error);
+  }
+}
+
+// Filter initial segments
+segments = filterValidSegments(segments);
+
+// Error display component
+function ErrorDisplay({ error }: { error: string }) {
+  return (
+    <div style={{
+      fontFamily: 'system-ui, -apple-system, sans-serif',
+      padding: '40px',
+      maxWidth: '600px',
+      margin: '0 auto',
+    }}>
+      <h1 style={{ color: '#dc2626', marginBottom: '16px' }}>
+        Failed to Load Segments
+      </h1>
+      <pre style={{
+        background: '#fef2f2',
+        border: '1px solid #fecaca',
+        borderRadius: '8px',
+        padding: '16px',
+        overflow: 'auto',
+        whiteSpace: 'pre-wrap',
+        wordBreak: 'break-word',
+        color: '#991b1b',
+        fontSize: '14px',
+      }}>
+        {error}
+      </pre>
+      <p style={{ marginTop: '16px', color: '#6b7280' }}>
+        Check the console for more details. Common issues:
+      </p>
+      <ul style={{ color: '#6b7280', marginTop: '8px', paddingLeft: '20px' }}>
+        <li>Segment files have syntax errors</li>
+        <li>Components are not exported correctly</li>
+        <li>Missing dependencies</li>
+      </ul>
+    </div>
+  );
+}
+
+// Render the app
+const rootElement = document.getElementById("root");
+if (rootElement) {
+  appRoot = createRoot(rootElement);
+
+  const renderApp = (showSkeleton = false) => {
+    const currentSegments = window.__SEGMENTS__ ?? segments;
+    const currentError = loadError || window.__SEGMENTS_ERROR__;
+
+    // Show skeleton while loading
+    if (showSkeleton && currentSegments.length === 0 && !currentError) {
+      appRoot?.render(
+        <ThemeProvider>
+          <AppSkeleton />
+        </ThemeProvider>
+      );
+      return;
+    }
+
+    // Show error if we have one and no valid segments
+    if (currentError && currentSegments.length === 0) {
+      appRoot?.render(<ErrorDisplay error={currentError} />);
+      return;
+    }
+
+    appRoot?.render(
+      <ThemeProvider>
+        <AppErrorBoundary>
+          <App segments={currentSegments} />
+        </AppErrorBoundary>
+      </ThemeProvider>
+    );
+  };
+
+  // Show skeleton immediately if no segments yet
+  if (segments.length === 0 && !loadError) {
+    renderApp(true);
+
+    // Load segments asynchronously and re-render
+    loadSegmentsFromVirtualModule().then(() => {
+      renderApp(false);
+    });
+  } else {
+    // We have segments from window, render immediately
+    renderApp(false);
+  }
+
+  // Listen for HMR updates from Segments plugin
+  window.addEventListener("segments:update", () => {
+    console.log("[Fragments] Refreshing viewer...");
+    // Re-render with updated segments
+    renderApp(false);
+  });
+}
+
+// HMR support for entry file and a11y invalidation
+// @ts-expect-error Vite HMR types
+if (import.meta.hot) {
+  // @ts-expect-error Vite HMR types
+  import.meta.hot.accept();
+
+  // Subscribe to a11y invalidation events from Vite plugin
+  // @ts-expect-error Vite HMR types
+  import.meta.hot.on("segments:a11y-invalidate", (data: {
+    components: string[];
+    file: string;
+    timestamp: number;
+  }) => {
+    console.log("[Fragments] A11y invalidation triggered for:", data.components.join(", "));
+
+    // Dispatch custom event for a11y service to handle
+    window.dispatchEvent(new CustomEvent("a11y-cache-invalidated", {
+      detail: {
+        components: data.components,
+        file: data.file,
+        timestamp: data.timestamp,
+      },
+    }));
+  });
+}

package/src/viewer/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './useHmrStatus.js';
+export * from './usePreviewBridge.js';

package/src/viewer/hooks/useA11yCache.ts

@@ -0,0 +1,383 @@
+/**
+ * Shared A11y Cache
+ *
+ * Provides a global cache for accessibility scan results that:
+ * 1. Persists in sessionStorage across page navigations
+ * 2. Is shared between Dashboard and AccessibilityPanel
+ * 3. Stores full violation details for rich UI display
+ * 4. Supports component-level invalidation
+ */
+
+import { BRAND } from '../../core/index.js';
+import type {
+  CachedA11yResult,
+  SerializedViolation,
+  A11ySummary,
+} from '../types/a11y.js';
+
+const CACHE_KEY = `${BRAND.storagePrefix}a11y-cache`;
+const CACHE_VERSION = 2; // Bumped for new schema with full violations
+
+/**
+ * Legacy interface for backward compatibility
+ * @deprecated Use CachedA11yResult instead
+ */
+export interface ComponentA11yData {
+  violations: number;
+  passes: number;
+  incomplete: number;
+  critical: number;
+  serious: number;
+  moderate: number;
+  minor: number;
+  scannedAt: number;
+  variant?: string;
+}
+
+interface A11yCacheData {
+  version: number;
+  components: Record<string, CachedA11yResult>;
+  lastFullScan?: number;
+}
+
+/**
+ * Load cache from sessionStorage
+ */
+function loadCache(): A11yCacheData {
+  try {
+    const stored = sessionStorage.getItem(CACHE_KEY);
+    if (stored) {
+      const data = JSON.parse(stored) as A11yCacheData;
+      if (data.version === CACHE_VERSION) {
+        return data;
+      }
+      // Version mismatch - clear old cache
+      sessionStorage.removeItem(CACHE_KEY);
+    }
+  } catch (e) {
+    // Ignore parse errors
+  }
+  return { version: CACHE_VERSION, components: {} };
+}
+
+/**
+ * Save cache to sessionStorage
+ */
+function saveCache(data: A11yCacheData): void {
+  try {
+    sessionStorage.setItem(CACHE_KEY, JSON.stringify(data));
+  } catch (e) {
+    // Storage might be full - try clearing old data
+    try {
+      sessionStorage.removeItem(CACHE_KEY);
+      sessionStorage.setItem(CACHE_KEY, JSON.stringify(data));
+    } catch {
+      // Ignore storage errors
+    }
+  }
+}
+
+/**
+ * Get cached a11y result for a component (full data)
+ */
+export function getComponentA11yResult(componentName: string): CachedA11yResult | null {
+  const cache = loadCache();
+  return cache.components[componentName] || null;
+}
+
+/**
+ * Get cached a11y data for a component (legacy format for backward compatibility)
+ */
+export function getComponentA11y(componentName: string): ComponentA11yData | null {
+  const result = getComponentA11yResult(componentName);
+  if (!result) return null;
+
+  return {
+    violations: result.violations.length,
+    passes: result.passes,
+    incomplete: result.incomplete,
+    critical: result.counts.critical,
+    serious: result.counts.serious,
+    moderate: result.counts.moderate,
+    minor: result.counts.minor,
+    scannedAt: result.scannedAt,
+    variant: result.variant,
+  };
+}
+
+/**
+ * Get all cached a11y data (full results)
+ */
+export function getAllA11yResults(): Record<string, CachedA11yResult> {
+  const cache = loadCache();
+  return cache.components;
+}
+
+/**
+ * Get all cached a11y data (legacy format)
+ */
+export function getAllA11yData(): Record<string, ComponentA11yData> {
+  const cache = loadCache();
+  const result: Record<string, ComponentA11yData> = {};
+
+  for (const [name, data] of Object.entries(cache.components)) {
+    result[name] = {
+      violations: data.violations.length,
+      passes: data.passes,
+      incomplete: data.incomplete,
+      critical: data.counts.critical,
+      serious: data.counts.serious,
+      moderate: data.counts.moderate,
+      minor: data.counts.minor,
+      scannedAt: data.scannedAt,
+      variant: data.variant,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Get timestamp of last full scan
+ */
+export function getLastFullScanTime(): number | undefined {
+  const cache = loadCache();
+  return cache.lastFullScan;
+}
+
+/**
+ * Update cache with full a11y result for a component
+ */
+export function updateComponentA11yResult(
+  componentName: string,
+  result: Omit<CachedA11yResult, 'componentName' | 'scannedAt'> & { scannedAt?: number }
+): void {
+  const cache = loadCache();
+  cache.components[componentName] = {
+    componentName,
+    ...result,
+    scannedAt: result.scannedAt || Date.now(),
+  };
+  saveCache(cache);
+
+  // Dispatch event for listeners
+  window.dispatchEvent(new CustomEvent('a11y-cache-updated', {
+    detail: {
+      componentName,
+      data: cache.components[componentName],
+      // Include legacy format for backward compatibility
+      legacyData: {
+        violations: result.violations.length,
+        passes: result.passes,
+        incomplete: result.incomplete,
+        critical: result.counts.critical,
+        serious: result.counts.serious,
+        moderate: result.counts.moderate,
+        minor: result.counts.minor,
+        scannedAt: result.scannedAt || Date.now(),
+        variant: result.variant,
+      },
+    },
+  }));
+}
+
+/**
+ * Update cache for a single component (legacy format, converted to new format)
+ */
+export function updateComponentA11y(
+  componentName: string,
+  data: Omit<ComponentA11yData, 'scannedAt'> & { scannedAt?: number },
+  violations?: SerializedViolation[]
+): void {
+  const cache = loadCache();
+
+  // Convert to new format
+  cache.components[componentName] = {
+    componentName,
+    violations: violations || [], // Use provided violations or empty array
+    passes: data.passes,
+    incomplete: data.incomplete,
+    scannedAt: data.scannedAt || Date.now(),
+    variant: data.variant,
+    counts: {
+      critical: data.critical,
+      serious: data.serious,
+      moderate: data.moderate,
+      minor: data.minor,
+    },
+  };
+  saveCache(cache);
+
+  // Dispatch event for listeners
+  window.dispatchEvent(new CustomEvent('a11y-cache-updated', {
+    detail: { componentName, data: cache.components[componentName] },
+  }));
+}
+
+/**
+ * Invalidate cache for specific components
+ * This marks them for re-scan without removing the data
+ */
+export function invalidateComponents(componentNames: string[]): void {
+  const cache = loadCache();
+  let changed = false;
+
+  for (const name of componentNames) {
+    if (cache.components[name]) {
+      // Set scannedAt to 0 to mark as stale
+      cache.components[name].scannedAt = 0;
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    saveCache(cache);
+
+    // Dispatch event for listeners
+    window.dispatchEvent(new CustomEvent('a11y-cache-invalidated', {
+      detail: { components: componentNames },
+    }));
+  }
+}
+
+/**
+ * Check if a component's cache is stale (needs re-scan)
+ */
+export function isComponentStale(componentName: string, maxAgeMs: number = 30000): boolean {
+  const cache = loadCache();
+  const data = cache.components[componentName];
+
+  if (!data) return true;
+  if (data.scannedAt === 0) return true; // Explicitly invalidated
+
+  return Date.now() - data.scannedAt > maxAgeMs;
+}
+
+/**
+ * Mark that a full scan was completed
+ */
+export function markFullScanComplete(): void {
+  const cache = loadCache();
+  cache.lastFullScan = Date.now();
+  saveCache(cache);
+}
+
+/**
+ * Clear all cached data
+ */
+export function clearA11yCache(): void {
+  try {
+    sessionStorage.removeItem(CACHE_KEY);
+  } catch (e) {
+    // Ignore
+  }
+  window.dispatchEvent(new CustomEvent('a11y-cache-cleared'));
+}
+
+/**
+ * Clear cache for a specific component
+ */
+export function clearComponentCache(componentName: string): void {
+  const cache = loadCache();
+  if (cache.components[componentName]) {
+    delete cache.components[componentName];
+    saveCache(cache);
+
+    window.dispatchEvent(new CustomEvent('a11y-cache-updated', {
+      detail: { componentName, data: null },
+    }));
+  }
+}
+
+/**
+ * Calculate summary from cached data
+ */
+export function getA11ySummary(): A11ySummary {
+  const cache = loadCache();
+  const components = Object.values(cache.components);
+
+  const summary: A11ySummary = {
+    accessibleComponents: 0,
+    totalComponents: components.length,
+    violationsByImpact: {
+      critical: 0,
+      serious: 0,
+      moderate: 0,
+      minor: 0,
+    },
+    topViolations: [],
+  };
+
+  // Track violations by rule ID for top violations
+  const violationsByRule = new Map<string, {
+    ruleId: string;
+    description: string;
+    impact: 'critical' | 'serious' | 'moderate' | 'minor' | null;
+    affectedComponents: Set<string>;
+  }>();
+
+  for (const comp of components) {
+    // Count by impact
+    summary.violationsByImpact.critical += comp.counts.critical;
+    summary.violationsByImpact.serious += comp.counts.serious;
+    summary.violationsByImpact.moderate += comp.counts.moderate;
+    summary.violationsByImpact.minor += comp.counts.minor;
+
+    // Check if accessible (no critical/serious)
+    if (comp.counts.critical === 0 && comp.counts.serious === 0) {
+      summary.accessibleComponents++;
+    }
+
+    // Aggregate violations by rule
+    for (const violation of comp.violations) {
+      const existing = violationsByRule.get(violation.id);
+      if (existing) {
+        existing.affectedComponents.add(comp.componentName);
+      } else {
+        violationsByRule.set(violation.id, {
+          ruleId: violation.id,
+          description: violation.description,
+          impact: violation.impact,
+          affectedComponents: new Set([comp.componentName]),
+        });
+      }
+    }
+  }
+
+  // Sort by number of affected components and take top 5
+  summary.topViolations = Array.from(violationsByRule.values())
+    .sort((a, b) => b.affectedComponents.size - a.affectedComponents.size)
+    .slice(0, 5)
+    .map(v => ({
+      ruleId: v.ruleId,
+      description: v.description,
+      impact: v.impact,
+      affectedComponents: Array.from(v.affectedComponents),
+    }));
+
+  return summary;
+}
+
+/**
+ * Get legacy summary format for backward compatibility
+ */
+export function getLegacyA11ySummary(): {
+  totalComponents: number;
+  accessibleComponents: number;
+  totalViolations: number;
+  totalCritical: number;
+  totalSerious: number;
+} {
+  const summary = getA11ySummary();
+  return {
+    totalComponents: summary.totalComponents,
+    accessibleComponents: summary.accessibleComponents,
+    totalViolations:
+      summary.violationsByImpact.critical +
+      summary.violationsByImpact.serious +
+      summary.violationsByImpact.moderate +
+      summary.violationsByImpact.minor,
+    totalCritical: summary.violationsByImpact.critical,
+    totalSerious: summary.violationsByImpact.serious,
+  };
+}