@fragments-sdk/viewer 0.2.1

package/src/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 '@fragments-sdk/core';
+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,
+  };
+}