@fragments-sdk/cli 0.2.2

package/src/viewer/utils/a11y-fixes.ts

@@ -0,0 +1,471 @@
+/**
+ * A11y Fixes - Static Fix Generators
+ *
+ * Rule-specific fix suggestions without AI. Provides:
+ * - "Why it matters" explanations
+ * - Before/after code examples
+ * - WCAG references
+ * - Specific fixes based on violation data
+ */
+
+import type { ImpactValue } from 'axe-core';
+import type { StaticFixSuggestion, ElementFix, SerializedNode } from '../types/a11y.js';
+
+/**
+ * WCAG criteria references
+ */
+const WCAG_CRITERIA: Record<string, { id: string; name: string; level: 'A' | 'AA' | 'AAA'; url: string }> = {
+  // Level A
+  '1.1.1': {
+    id: '1.1.1',
+    name: 'Non-text Content',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/non-text-content',
+  },
+  '1.3.1': {
+    id: '1.3.1',
+    name: 'Info and Relationships',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships',
+  },
+  '2.1.1': {
+    id: '2.1.1',
+    name: 'Keyboard',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/keyboard',
+  },
+  '2.4.4': {
+    id: '2.4.4',
+    name: 'Link Purpose (In Context)',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context',
+  },
+  '4.1.2': {
+    id: '4.1.2',
+    name: 'Name, Role, Value',
+    level: 'A',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/name-role-value',
+  },
+  // Level AA
+  '1.4.3': {
+    id: '1.4.3',
+    name: 'Contrast (Minimum)',
+    level: 'AA',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum',
+  },
+  '1.4.4': {
+    id: '1.4.4',
+    name: 'Resize Text',
+    level: 'AA',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/resize-text',
+  },
+  '2.4.6': {
+    id: '2.4.6',
+    name: 'Headings and Labels',
+    level: 'AA',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels',
+  },
+  // Level AAA
+  '1.4.6': {
+    id: '1.4.6',
+    name: 'Contrast (Enhanced)',
+    level: 'AAA',
+    url: 'https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced',
+  },
+};
+
+/**
+ * Static fix suggestions for common accessibility rules
+ */
+const STATIC_FIXES: Record<string, StaticFixSuggestion> = {
+  'color-contrast': {
+    whyItMatters:
+      'Low contrast text is difficult to read for users with low vision, color blindness, or in bright environments like outdoor settings.',
+    howToFix:
+      'Increase the contrast ratio between text and background colors. Normal text requires 4.5:1, large text (18pt or 14pt bold) requires 3:1.',
+    badExample: '<button style="color: #888; background: #fff">Submit</button>',
+    goodExample: '<button style="color: #333; background: #fff">Submit</button>',
+    wcagCriterion: WCAG_CRITERIA['1.4.3'],
+  },
+  'image-alt': {
+    whyItMatters:
+      'Screen reader users cannot perceive images and rely on alternative text to understand visual content.',
+    howToFix:
+      'Add descriptive alt text that conveys the purpose or content of the image. For decorative images, use alt="".',
+    badExample: '<img src="hero.jpg">',
+    goodExample: '<img src="hero.jpg" alt="Team collaboration in modern office">',
+    wcagCriterion: WCAG_CRITERIA['1.1.1'],
+  },
+  'button-name': {
+    whyItMatters:
+      'Screen reader users need accessible names to understand what a button does. Without a name, they hear "button" with no context.',
+    howToFix:
+      'Add text content, an aria-label, or aria-labelledby attribute to give the button an accessible name.',
+    badExample: '<button><svg>...</svg></button>',
+    goodExample: '<button aria-label="Close dialog"><svg>...</svg></button>',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'link-name': {
+    whyItMatters:
+      'Screen reader users navigate by links and need descriptive text to understand each link\'s destination or purpose.',
+    howToFix:
+      'Use descriptive link text instead of generic phrases. Avoid "click here" or "read more" without context.',
+    badExample: '<a href="/docs">Click here</a>',
+    goodExample: '<a href="/docs">View documentation</a>',
+    wcagCriterion: WCAG_CRITERIA['2.4.4'],
+  },
+  'label': {
+    whyItMatters:
+      'Form inputs without labels are difficult for screen reader users to understand and for all users to identify.',
+    howToFix:
+      'Associate a <label> element with the input using the for/id attributes, or wrap the input in a label element.',
+    badExample: '<input type="text" placeholder="Email">',
+    goodExample: '<label for="email">Email</label>\n<input type="text" id="email">',
+    wcagCriterion: WCAG_CRITERIA['1.3.1'],
+  },
+  'aria-valid-attr': {
+    whyItMatters:
+      'Invalid ARIA attributes are ignored by assistive technologies and may indicate other accessibility issues.',
+    howToFix:
+      'Use only valid ARIA attributes from the WAI-ARIA specification. Check spelling and ensure attributes apply to the element type.',
+    badExample: '<button aria-expanded="true" aria-describedby="">Submit</button>',
+    goodExample: '<button aria-expanded="true" aria-describedby="help-text">Submit</button>',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'aria-valid-attr-value': {
+    whyItMatters:
+      'ARIA attributes with invalid values are ignored or misinterpreted by assistive technologies.',
+    howToFix:
+      'Ensure ARIA attribute values match the expected format (boolean, ID reference, token, etc.).',
+    badExample: '<div aria-hidden="yes">Hidden content</div>',
+    goodExample: '<div aria-hidden="true">Hidden content</div>',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'aria-required-attr': {
+    whyItMatters:
+      'ARIA roles require specific attributes to function correctly with assistive technologies.',
+    howToFix:
+      'Add all required ARIA attributes for the role being used.',
+    badExample: '<div role="checkbox">Accept terms</div>',
+    goodExample: '<div role="checkbox" aria-checked="false">Accept terms</div>',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+  'heading-order': {
+    whyItMatters:
+      'Screen reader users navigate by headings. Skipped heading levels make it harder to understand document structure.',
+    howToFix:
+      'Use headings in sequential order (h1 → h2 → h3). Don\'t skip levels for styling purposes.',
+    badExample: '<h1>Page Title</h1>\n<h4>Section</h4>',
+    goodExample: '<h1>Page Title</h1>\n<h2>Section</h2>',
+    wcagCriterion: WCAG_CRITERIA['1.3.1'],
+  },
+  'tabindex': {
+    whyItMatters:
+      'Positive tabindex values create unexpected keyboard navigation order, confusing keyboard-only users.',
+    howToFix:
+      'Use tabindex="0" to add elements to natural tab order, or tabindex="-1" to remove them. Avoid positive values.',
+    badExample: '<button tabindex="5">First</button>\n<button tabindex="1">Second</button>',
+    goodExample: '<button>First</button>\n<button>Second</button>',
+    wcagCriterion: WCAG_CRITERIA['2.1.1'],
+  },
+  'duplicate-id': {
+    whyItMatters:
+      'Duplicate IDs can cause aria-labelledby, aria-describedby, and label associations to reference the wrong element.',
+    howToFix:
+      'Ensure each id attribute value is unique within the page.',
+    badExample: '<input id="name">\n<input id="name">',
+    goodExample: '<input id="first-name">\n<input id="last-name">',
+    wcagCriterion: WCAG_CRITERIA['4.1.2'],
+  },
+};
+
+/**
+ * Get static fix suggestion for a rule
+ */
+export function getStaticFix(ruleId: string): StaticFixSuggestion | null {
+  return STATIC_FIXES[ruleId] || null;
+}
+
+/**
+ * Parse contrast ratio data from axe-core node data
+ */
+function parseContrastData(node: SerializedNode): {
+  fgColor?: string;
+  bgColor?: string;
+  contrastRatio?: number;
+  requiredRatio?: number;
+  fontSize?: string;
+  fontWeight?: string;
+} | null {
+  const anyData = node.any?.[0]?.data as Record<string, unknown> | undefined;
+  if (!anyData) return null;
+
+  return {
+    fgColor: anyData.fgColor as string | undefined,
+    bgColor: anyData.bgColor as string | undefined,
+    contrastRatio: anyData.contrastRatio as number | undefined,
+    requiredRatio: anyData.expectedContrastRatio as number | undefined,
+    fontSize: anyData.fontSize as string | undefined,
+    fontWeight: anyData.fontWeight as string | undefined,
+  };
+}
+
+/**
+ * Generate a specific fix for a color-contrast violation
+ */
+function generateContrastFix(node: SerializedNode): ElementFix | null {
+  const data = parseContrastData(node);
+  if (!data?.fgColor || !data?.bgColor) return null;
+
+  const { fgColor, bgColor, contrastRatio, requiredRatio } = data;
+
+  // Safely convert to number and format
+  const currentRatioNum = typeof contrastRatio === 'number' ? contrastRatio : parseFloat(String(contrastRatio || ''));
+  const requiredRatioNum = typeof requiredRatio === 'number' ? requiredRatio : parseFloat(String(requiredRatio || ''));
+
+  const currentRatio = !isNaN(currentRatioNum) ? currentRatioNum.toFixed(2) : 'unknown';
+  const required = !isNaN(requiredRatioNum) ? requiredRatioNum.toFixed(1) : '4.5';
+
+  // Suggest darkening text if it's light, or lightening if it's dark
+  const suggestion = `Adjust colors to meet ${required}:1 contrast ratio (currently ${currentRatio}:1)`;
+
+  return {
+    originalHtml: node.html,
+    fixedHtml: node.html, // Can't auto-generate fixed HTML without color calculation
+    explanation: `Text color ${fgColor} on background ${bgColor} has insufficient contrast. ${suggestion}`,
+    autoFixable: false,
+  };
+}
+
+/**
+ * Generate a specific fix for an image-alt violation
+ */
+function generateAltTextFix(node: SerializedNode): ElementFix | null {
+  const html = node.html;
+
+  // Extract src to help generate meaningful alt text suggestion
+  const srcMatch = html.match(/src=["']([^"']+)["']/);
+  const src = srcMatch?.[1] || '';
+  const filename = src.split('/').pop()?.replace(/\.[^.]+$/, '') || 'image';
+
+  // Generate suggested alt text based on filename
+  const suggestedAlt = filename
+    .replace(/[-_]/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .toLowerCase();
+
+  // Create fixed HTML
+  let fixedHtml = html;
+  if (html.includes('alt=""') || html.includes("alt=''")) {
+    // Decorative image marked correctly, but flagged - might need real alt
+    fixedHtml = html.replace(/alt=["'][^"']*["']/, `alt="${suggestedAlt}"`);
+  } else if (html.includes('alt=')) {
+    // Has alt but it's not descriptive enough
+    fixedHtml = html.replace(/alt=["'][^"']*["']/, `alt="${suggestedAlt}"`);
+  } else {
+    // Missing alt entirely
+    fixedHtml = html.replace(/<img/, `<img alt="${suggestedAlt}"`);
+  }
+
+  return {
+    originalHtml: html,
+    fixedHtml,
+    explanation: `Add descriptive alt text that describes the image content or purpose. If decorative, use alt="".`,
+    autoFixable: true,
+  };
+}
+
+/**
+ * Generate a specific fix for a button-name violation
+ */
+function generateButtonNameFix(node: SerializedNode): ElementFix | null {
+  const html = node.html;
+
+  // Check if it's an icon-only button
+  const hasOnlySvg = /<button[^>]*>[\s]*<svg[^>]*>[\s\S]*<\/svg>[\s]*<\/button>/i.test(html);
+  const hasOnlyImg = /<button[^>]*>[\s]*<img[^>]*\/?>\s*<\/button>/i.test(html);
+
+  let fixedHtml = html;
+  let explanation = '';
+
+  if (hasOnlySvg || hasOnlyImg) {
+    // Add aria-label for icon buttons
+    fixedHtml = html.replace(/<button/, '<button aria-label="[describe action]"');
+    explanation = 'Add aria-label to describe the button\'s action for screen reader users.';
+  } else {
+    // Add visible text content
+    fixedHtml = html.replace(/<\/button>/, '[Button text]</button>');
+    explanation = 'Add visible text content or aria-label that describes the button\'s purpose.';
+  }
+
+  return {
+    originalHtml: html,
+    fixedHtml,
+    explanation,
+    autoFixable: false, // Requires human decision on button purpose
+  };
+}
+
+/**
+ * Generate a specific fix for a link-name violation
+ */
+function generateLinkNameFix(node: SerializedNode): ElementFix | null {
+  const html = node.html;
+
+  // Check common patterns
+  const hasOnlySvg = /<a[^>]*>[\s]*<svg[^>]*>[\s\S]*<\/svg>[\s]*<\/a>/i.test(html);
+  const hasOnlyImg = /<a[^>]*>[\s]*<img[^>]*\/?>\s*<\/a>/i.test(html);
+  const isEmpty = /<a[^>]*>\s*<\/a>/i.test(html);
+
+  let fixedHtml = html;
+  let explanation = '';
+
+  if (hasOnlySvg || hasOnlyImg) {
+    fixedHtml = html.replace(/<a/, '<a aria-label="[describe destination]"');
+    explanation = 'Add aria-label to describe where the link goes.';
+  } else if (isEmpty) {
+    fixedHtml = html.replace(/<\/a>/, '[Link text]</a>');
+    explanation = 'Add descriptive text content that indicates the link\'s destination.';
+  } else {
+    explanation = 'Ensure link text is descriptive. Avoid generic text like "click here" or "read more".';
+  }
+
+  return {
+    originalHtml: html,
+    fixedHtml,
+    explanation,
+    autoFixable: false,
+  };
+}
+
+/**
+ * Generate a specific fix for a label violation
+ */
+function generateLabelFix(node: SerializedNode): ElementFix | null {
+  const html = node.html;
+
+  // Extract input type and any existing identifiers
+  const typeMatch = html.match(/type=["']([^"']+)["']/);
+  const type = typeMatch?.[1] || 'text';
+  const idMatch = html.match(/id=["']([^"']+)["']/);
+  const id = idMatch?.[1];
+
+  let fixedHtml = html;
+  let explanation = '';
+
+  if (id) {
+    // Has ID, suggest adding label element
+    const labelText = type.charAt(0).toUpperCase() + type.slice(1);
+    explanation = `Add a <label for="${id}">${labelText}</label> element before this input.`;
+  } else {
+    // No ID, add one and suggest label
+    const suggestedId = `input-${type}-${Date.now()}`;
+    fixedHtml = html.replace(/<input/, `<input id="${suggestedId}"`);
+    explanation = `Add an id attribute and associate with a label: <label for="${suggestedId}">Label text</label>`;
+  }
+
+  return {
+    originalHtml: html,
+    fixedHtml,
+    explanation,
+    autoFixable: false,
+  };
+}
+
+/**
+ * Fix generator registry
+ */
+type FixGenerator = (node: SerializedNode) => ElementFix | null;
+
+const FIX_GENERATORS: Record<string, FixGenerator> = {
+  'color-contrast': generateContrastFix,
+  'image-alt': generateAltTextFix,
+  'button-name': generateButtonNameFix,
+  'link-name': generateLinkNameFix,
+  'label': generateLabelFix,
+};
+
+/**
+ * Generate a specific fix for a violation node
+ */
+export function generateElementFix(ruleId: string, node: SerializedNode): ElementFix | null {
+  const generator = FIX_GENERATORS[ruleId];
+  if (!generator) return null;
+  return generator(node);
+}
+
+/**
+ * Get impact description for UI display
+ */
+export function getImpactDescription(impact: ImpactValue | null): string {
+  switch (impact) {
+    case 'critical':
+      return 'Critical issues completely block access for some users';
+    case 'serious':
+      return 'Serious issues make content very difficult to access';
+    case 'moderate':
+      return 'Moderate issues cause some difficulty for users';
+    case 'minor':
+      return 'Minor issues may cause slight inconvenience';
+    default:
+      return 'Impact level not determined';
+  }
+}
+
+/**
+ * Get impact color class for styling
+ */
+export function getImpactColorClass(impact: ImpactValue | null): {
+  bg: string;
+  text: string;
+  border: string;
+  borderLeft: string;
+} {
+  switch (impact) {
+    case 'critical':
+      return {
+        bg: 'bg-red-100 dark:bg-red-950/50',
+        text: 'text-red-700 dark:text-red-300',
+        border: 'border-red-300 dark:border-red-700',
+        borderLeft: 'border-l-red-500',
+      };
+    case 'serious':
+      return {
+        bg: 'bg-orange-100 dark:bg-orange-950/50',
+        text: 'text-orange-700 dark:text-orange-300',
+        border: 'border-orange-300 dark:border-orange-700',
+        borderLeft: 'border-l-orange-500',
+      };
+    case 'moderate':
+      return {
+        bg: 'bg-amber-100 dark:bg-amber-950/50',
+        text: 'text-amber-700 dark:text-amber-300',
+        border: 'border-amber-300 dark:border-amber-700',
+        borderLeft: 'border-l-amber-500',
+      };
+    case 'minor':
+    default:
+      return {
+        bg: 'bg-yellow-100 dark:bg-yellow-950/50',
+        text: 'text-yellow-700 dark:text-yellow-300',
+        border: 'border-yellow-300 dark:border-yellow-700',
+        borderLeft: 'border-l-yellow-500',
+      };
+  }
+}
+
+/**
+ * Extract WCAG tags from a violation's tags array
+ */
+export function extractWcagTags(tags: string[]): string[] {
+  return tags.filter(tag => tag.startsWith('wcag'));
+}
+
+/**
+ * Get readable WCAG criterion from tag (e.g., 'wcag143' -> '1.4.3')
+ */
+export function parseWcagTag(tag: string): string | null {
+  const match = tag.match(/wcag(\d)(\d)(\d)/);
+  if (!match) return null;
+  return `${match[1]}.${match[2]}.${match[3]}`;
+}