@fragments-sdk/cli 0.10.1 → 0.12.1

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

@@ -1,509 +0,0 @@
-/**
- * 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';
-import { parseColor, suggestFix, rgbToHex } from '../../theme/contrast.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/WCAG22/Understanding/non-text-content',
-  },
-  '1.3.1': {
-    id: '1.3.1',
-    name: 'Info and Relationships',
-    level: 'A',
-    url: 'https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships',
-  },
-  '2.1.1': {
-    id: '2.1.1',
-    name: 'Keyboard',
-    level: 'A',
-    url: 'https://www.w3.org/WAI/WCAG22/Understanding/keyboard',
-  },
-  '2.4.4': {
-    id: '2.4.4',
-    name: 'Link Purpose (In Context)',
-    level: 'A',
-    url: 'https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context',
-  },
-  '4.1.2': {
-    id: '4.1.2',
-    name: 'Name, Role, Value',
-    level: 'A',
-    url: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value',
-  },
-  // Level AA
-  '1.4.3': {
-    id: '1.4.3',
-    name: 'Contrast (Minimum)',
-    level: 'AA',
-    url: 'https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum',
-  },
-  '1.4.4': {
-    id: '1.4.4',
-    name: 'Resize Text',
-    level: 'AA',
-    url: 'https://www.w3.org/WAI/WCAG22/Understanding/resize-text',
-  },
-  '2.4.6': {
-    id: '2.4.6',
-    name: 'Headings and Labels',
-    level: 'AA',
-    url: 'https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels',
-  },
-  '2.5.8': {
-    id: '2.5.8',
-    name: 'Target Size (Minimum)',
-    level: 'AA',
-    url: 'https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum',
-  },
-  // Level AAA
-  '1.4.6': {
-    id: '1.4.6',
-    name: 'Contrast (Enhanced)',
-    level: 'AAA',
-    url: 'https://www.w3.org/WAI/WCAG22/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'],
-  },
-  'target-size-minimum': {
-    whyItMatters:
-      'Small touch targets are difficult to activate for users with motor impairments or when using touch input.',
-    howToFix:
-      'Increase the interactive target to at least 24x24 CSS pixels, or add sufficient padding around the control.',
-    badExample: '<button style="width: 16px; height: 16px">×</button>',
-    goodExample: '<button style="min-width: 24px; min-height: 24px; padding: 4px">×</button>',
-    wcagCriterion: WCAG_CRITERIA['2.5.8'],
-  },
-};
-
-/**
- * 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: ratio, requiredRatio } = data;
-
-  // Safely convert to number and format
-  const currentRatioNum = typeof ratio === 'number' ? ratio : parseFloat(String(ratio || ''));
-  const requiredRatioNum = typeof requiredRatio === 'number' ? requiredRatio : parseFloat(String(requiredRatio || ''));
-
-  const currentRatio = !isNaN(currentRatioNum) ? currentRatioNum.toFixed(2) : 'unknown';
-  const required = !isNaN(requiredRatioNum) ? requiredRatioNum : 4.5;
-
-  // Use real color math to suggest a corrected foreground color
-  try {
-    const fgRgb = parseColor(fgColor);
-    const bgRgb = parseColor(bgColor);
-    const correctedHex = suggestFix(fgRgb, bgRgb, required);
-
-    return {
-      originalHtml: node.html,
-      fixedHtml: node.html,
-      explanation: `Text color ${fgColor} on background ${bgColor} has insufficient contrast (${currentRatio}:1, need ${required}:1). Suggested foreground: ${correctedHex}`,
-      autoFixable: true,
-    };
-  } catch {
-    // Fall back to non-auto-fixable if color parsing fails
-    return {
-      originalHtml: node.html,
-      fixedHtml: node.html,
-      explanation: `Text color ${fgColor} on background ${bgColor} has insufficient contrast (${currentRatio}:1, need ${required}:1). Adjust the foreground color to meet the required ratio.`,
-      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 styling for inline styles and Badge variant mapping
- */
-export function getImpactColorClass(impact: ImpactValue | null): {
-  variant: 'error' | 'warning' | 'info' | 'default';
-  color: string;
-  bg: string;
-  text: string;
-  border: string;
-  borderLeft: string;
-} {
-  switch (impact) {
-    case 'critical':
-      return {
-        variant: 'error',
-        color: 'var(--color-danger)',
-        bg: 'var(--color-danger-bg)',
-        text: 'var(--color-danger)',
-        border: 'var(--color-danger)',
-        borderLeft: 'var(--color-danger)',
-      };
-    case 'serious':
-      return {
-        variant: 'error',
-        color: 'var(--color-danger)',
-        bg: 'var(--color-danger-bg)',
-        text: 'var(--color-danger)',
-        border: 'var(--color-danger)',
-        borderLeft: 'var(--color-danger)',
-      };
-    case 'moderate':
-      return {
-        variant: 'warning',
-        color: 'var(--color-warning)',
-        bg: 'var(--color-warning-bg)',
-        text: 'var(--color-warning)',
-        border: 'var(--color-warning)',
-        borderLeft: 'var(--color-warning)',
-      };
-    case 'minor':
-    default:
-      return {
-        variant: 'info',
-        color: 'var(--color-info)',
-        bg: 'var(--color-info-bg)',
-        text: 'var(--color-info)',
-        border: 'var(--color-info)',
-        borderLeft: 'var(--color-info)',
-      };
-  }
-}
-
-/**
- * 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]}`;
-}