@sc4rfurryx/proteusjs 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sc4rfurryx/proteusjs",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "type": "module",
   "description": "The Modern Web Development Framework for Accessible, Responsive, and High-Performance Applications. Intelligent container queries, fluid typography, WCAG compliance, and performance optimization.",
   "main": "dist/proteus.js",
@@ -89,8 +89,13 @@
     "benchmark": "vitest run tests/benchmarks/performance-benchmark.ts",
     "accessibility": "vitest run tests/validation/accessibility-validation.test.ts",
     "docs:build": "typedoc src/index.ts",
-    "prepublishOnly": "npm run validate && npm run build:prod",
-    "release": "npm run validate && npm run build:prod && npm publish"
+    "prepublishOnly": "npm run build:prod",
+    "release": "npm run validate && npm run build:prod && npm publish",
+    "release:patch": "node scripts/release.js patch",
+    "release:minor": "node scripts/release.js minor",
+    "release:major": "node scripts/release.js major",
+    "release:dry": "node scripts/release.js patch --dry-run",
+    "publish:dev": "node scripts/publish-dev.js"
   },
   "keywords": [
     "responsive",
@@ -152,4 +157,4 @@
   "dependencies": {
     "tslib": "^2.8.1"
   }
-}
+}

package/src/index.ts

@@ -47,7 +47,7 @@ export type { PopoverOptions, PopoverController } from './modules/popover';
 export type { ContainerOptions } from './modules/container';
 export type { FluidTypeOptions, FluidTypeResult } from './modules/typography';
 export type { AuditOptions, AuditReport, AuditViolation } from './modules/a11y-audit';
-export type { Controller, DialogOptions, TooltipOptions, ComboboxOptions, ListboxOptions, FocusTrapController } from './modules/a11y-primitives';
+export type { Controller, DialogOptions, TooltipOptions, FocusTrapController } from './modules/a11y-primitives';
 export type { SpeculationOptions, ContentVisibilityOptions } from './modules/perf';
 
 // Utility exports

package/src/modules/a11y-audit/index.ts

@@ -1,6 +1,6 @@
-/**
+/**
  * @sc4rfurryx/proteusjs/a11y-audit
- * Accessibility audits for development (dev-only)
+ * Lightweight accessibility audits for development
  * 
  * @version 1.1.0
  * @author sc4rfurry
@@ -10,7 +10,6 @@
 export interface AuditOptions {
   rules?: string[];
   format?: 'console' | 'json';
-  openInBrowser?: boolean;
 }
 
 export interface AuditViolation {
@@ -18,591 +17,68 @@ export interface AuditViolation {
   impact: 'minor' | 'moderate' | 'serious' | 'critical';
   nodes: number;
   help: string;
-  fix: string;
-  elements?: Element[];
 }
 
 export interface AuditReport {
   violations: AuditViolation[];
   passes: number;
-  incomplete: number;
   timestamp: number;
   url: string;
 }
 
-/**
- * Run accessibility audits with actionable output
- * DEV-ONLY: This module should be tree-shaken in production
- */
 export async function audit(
   target: Document | Element = document,
   options: AuditOptions = {}
 ): Promise<AuditReport> {
-  // Ensure this only runs in development
-  if (process.env['NODE_ENV'] === 'production') {
-    console.warn('a11y-audit should not be used in production');
-    return {
-      violations: [],
-      passes: 0,
-      incomplete: 0,
-      timestamp: Date.now(),
-      url: window.location.href
-    };
+  if (typeof window === 'undefined' || process.env['NODE_ENV'] === 'production') {
+    return { violations: [], passes: 0, timestamp: Date.now(), url: '' };
   }
 
-  const {
-    rules = ['color-contrast', 'heading-order', 'image-alt', 'label', 'link-name', 'button-name'],
-    format = 'console',
-    openInBrowser = false
-  } = options;
-
+  const { rules = ['images', 'headings', 'forms'], format = 'console' } = options;
   const violations: AuditViolation[] = [];
   let passes = 0;
-  let incomplete = 0;
-
-  // Basic accessibility checks
-  const checks = {
-    'color-contrast': checkColorContrast,
-    'heading-order': checkHeadingOrder,
-    'image-alt': checkImageAlt,
-    'label': checkFormLabels,
-    'link-name': checkLinkNames,
-    'button-name': checkButtonNames,
-    'focus-visible': checkFocusVisible,
-    'aria-labels': checkAriaLabels,
-    'landmark-roles': checkLandmarkRoles,
-    'skip-links': checkSkipLinks
-  };
-
-  // Run selected checks
-  for (const ruleId of rules) {
-    if (checks[ruleId as keyof typeof checks]) {
-      try {
-        const result = await checks[ruleId as keyof typeof checks](target);
-        if (result.violations.length > 0) {
-          violations.push(...result.violations);
-        } else {
-          passes++;
-        }
-      } catch (error) {
-        incomplete++;
-        console.warn(`Failed to run accessibility check: ${ruleId}`, error);
-      }
-    }
-  }
-
-  const report: AuditReport = {
-    violations,
-    passes,
-    incomplete,
-    timestamp: Date.now(),
-    url: window.location.href
-  };
-
-  // Output results
-  if (format === 'console') {
-    outputToConsole(report);
-  }
-
-  if (openInBrowser) {
-    openReportInBrowser(report);
-  }
-
-  return report;
-}
-
-// Individual check functions
-async function checkColorContrast(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-  const elements = target.querySelectorAll('*');
-
-  elements.forEach(element => {
-    const style = getComputedStyle(element);
-    const color = style.color;
-    const backgroundColor = style.backgroundColor;
-
-    // Simple contrast check (would need more sophisticated implementation)
-    if (color && backgroundColor && color !== 'rgba(0, 0, 0, 0)' && backgroundColor !== 'rgba(0, 0, 0, 0)') {
-      const contrast = calculateContrast(color, backgroundColor);
-      if (contrast < 4.5) {
-        violations.push({
-          id: 'color-contrast',
-          impact: 'serious',
-          nodes: 1,
-          help: 'Elements must have sufficient color contrast',
-          fix: `Increase contrast ratio to at least 4.5:1. Current: ${contrast.toFixed(2)}:1`,
-          elements: [element]
-        });
-      }
-    }
-  });
-
-  return { violations };
-}
 
-async function checkHeadingOrder(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-  const headings = target.querySelectorAll('h1, h2, h3, h4, h5, h6');
-  
-  let lastLevel = 0;
-  headings.forEach(heading => {
-    const level = parseInt(heading.tagName.charAt(1));
-    if (level > lastLevel + 1) {
+  if (rules.includes('images')) {
+    const imgs = target.querySelectorAll('img:not([alt])');
+    if (imgs.length > 0) {
       violations.push({
-        id: 'heading-order',
-        impact: 'moderate',
-        nodes: 1,
-        help: 'Heading levels should only increase by one',
-        fix: `Change ${heading.tagName} to H${lastLevel + 1} or add intermediate headings`,
-        elements: [heading]
+        id: 'image-alt', impact: 'critical', nodes: imgs.length, help: 'Images need alt text'
       });
     }
-    lastLevel = level;
-  });
-
-  return { violations };
-}
-
-async function checkImageAlt(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-  const images = target.querySelectorAll('img');
-
-  images.forEach(img => {
-    if (!img.hasAttribute('alt')) {
-      violations.push({
-        id: 'image-alt',
-        impact: 'critical',
-        nodes: 1,
-        help: 'Images must have alternative text',
-        fix: 'Add alt attribute with descriptive text or alt="" for decorative images',
-        elements: [img]
-      });
-    }
-  });
-
-  return { violations };
-}
-
-async function checkFormLabels(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-  const inputs = target.querySelectorAll('input, select, textarea');
-
-  inputs.forEach(input => {
-    const hasLabel = input.hasAttribute('aria-label') || 
-                    input.hasAttribute('aria-labelledby') ||
-                    target.querySelector(`label[for="${input.id}"]`) ||
-                    input.closest('label');
-
-    if (!hasLabel) {
-      violations.push({
-        id: 'label',
-        impact: 'critical',
-        nodes: 1,
-        help: 'Form elements must have labels',
-        fix: 'Add a label element, aria-label, or aria-labelledby attribute',
-        elements: [input]
-      });
-    }
-  });
-
-  return { violations };
-}
-
-async function checkLinkNames(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-  const links = target.querySelectorAll('a[href]');
-
-  links.forEach(link => {
-    const text = link.textContent?.trim();
-    const ariaLabel = link.getAttribute('aria-label');
-    
-    if (!text && !ariaLabel) {
-      violations.push({
-        id: 'link-name',
-        impact: 'serious',
-        nodes: 1,
-        help: 'Links must have discernible text',
-        fix: 'Add descriptive text content or aria-label attribute',
-        elements: [link]
-      });
-    }
-  });
-
-  return { violations };
-}
-
-async function checkButtonNames(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-  const buttons = target.querySelectorAll('button, input[type="button"], input[type="submit"]');
-
-  buttons.forEach(button => {
-    const text = button.textContent?.trim();
-    const ariaLabel = button.getAttribute('aria-label');
-    const value = button.getAttribute('value');
-    
-    if (!text && !ariaLabel && !value) {
-      violations.push({
-        id: 'button-name',
-        impact: 'serious',
-        nodes: 1,
-        help: 'Buttons must have discernible text',
-        fix: 'Add text content, aria-label, or value attribute',
-        elements: [button]
-      });
-    }
-  });
-
-  return { violations };
-}
-
-async function checkFocusVisible(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-  const focusableElements = target.querySelectorAll(
-    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-  );
-
-  focusableElements.forEach(element => {
-    const styles = getComputedStyle(element as HTMLElement);
-    const hasVisibleFocus = styles.outline !== 'none' && styles.outline !== '0px' &&
-                           styles.outline !== '0' && styles.outlineWidth !== '0px';
-
-    // Check if element has custom focus styles
-    const hasCustomFocus = styles.boxShadow.includes('inset') ||
-                          styles.border !== styles.borderColor ||
-                          element.hasAttribute('data-focus-visible');
-
-    if (!hasVisibleFocus && !hasCustomFocus) {
-      violations.push({
-        id: 'focus-visible',
-        impact: 'serious',
-        nodes: 1,
-        help: 'Interactive elements must have visible focus indicators',
-        fix: 'Add outline, box-shadow, or other visible focus styles',
-        elements: [element]
-      });
-    }
-  });
-
-  return { violations };
-}
-
-async function checkAriaLabels(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-
-  // Check for aria-labelledby pointing to non-existent elements
-  const elementsWithLabelledBy = target.querySelectorAll('[aria-labelledby]');
-  elementsWithLabelledBy.forEach(element => {
-    const labelledBy = element.getAttribute('aria-labelledby');
-    if (labelledBy) {
-      const labelIds = labelledBy.split(' ');
-      const missingIds = labelIds.filter(id => !target.querySelector(`#${id}`));
-
-      if (missingIds.length > 0) {
-        violations.push({
-          id: 'aria-labelledby-invalid',
-          impact: 'serious',
-          nodes: 1,
-          help: 'aria-labelledby must reference existing elements',
-          fix: `Fix or remove references to missing IDs: ${missingIds.join(', ')}`,
-          elements: [element]
-        });
-      }
-    }
-  });
-
-  // Check for aria-describedby pointing to non-existent elements
-  const elementsWithDescribedBy = target.querySelectorAll('[aria-describedby]');
-  elementsWithDescribedBy.forEach(element => {
-    const describedBy = element.getAttribute('aria-describedby');
-    if (describedBy) {
-      const descriptionIds = describedBy.split(' ');
-      const missingIds = descriptionIds.filter(id => !target.querySelector(`#${id}`));
-
-      if (missingIds.length > 0) {
-        violations.push({
-          id: 'aria-describedby-invalid',
-          impact: 'moderate',
-          nodes: 1,
-          help: 'aria-describedby must reference existing elements',
-          fix: `Fix or remove references to missing IDs: ${missingIds.join(', ')}`,
-          elements: [element]
-        });
-      }
-    }
-  });
-
-  return { violations };
-}
-
-async function checkLandmarkRoles(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-
-  // Check for missing main landmark
-  const mainElements = target.querySelectorAll('main, [role="main"]');
-  if (mainElements.length === 0) {
-    violations.push({
-      id: 'landmark-main-missing',
-      impact: 'moderate',
-      nodes: 0,
-      help: 'Page should have a main landmark',
-      fix: 'Add a <main> element or role="main" to identify the main content area'
-    });
-  } else if (mainElements.length > 1) {
-    violations.push({
-      id: 'landmark-main-multiple',
-      impact: 'moderate',
-      nodes: mainElements.length,
-      help: 'Page should have only one main landmark',
-      fix: 'Ensure only one main element or role="main" exists per page',
-      elements: Array.from(mainElements)
-    });
+    passes += target.querySelectorAll('img[alt]').length;
   }
 
-  // Check for navigation landmarks without labels when multiple exist
-  const navElements = target.querySelectorAll('nav, [role="navigation"]');
-  if (navElements.length > 1) {
-    navElements.forEach(nav => {
-      const hasLabel = nav.hasAttribute('aria-label') ||
-                      nav.hasAttribute('aria-labelledby') ||
-                      nav.querySelector('h1, h2, h3, h4, h5, h6');
-
-      if (!hasLabel) {
-        violations.push({
-          id: 'landmark-nav-unlabeled',
-          impact: 'moderate',
-          nodes: 1,
-          help: 'Multiple navigation landmarks should be labeled',
-          fix: 'Add aria-label or aria-labelledby to distinguish navigation areas',
-          elements: [nav]
-        });
-      }
-    });
-  }
-
-  return { violations };
-}
-
-async function checkSkipLinks(target: Document | Element): Promise<{ violations: AuditViolation[] }> {
-  const violations: AuditViolation[] = [];
-
-  // Check for skip links in documents with navigation
-  const navElements = target.querySelectorAll('nav, [role="navigation"]');
-  const mainElement = target.querySelector('main, [role="main"]');
-
-  if (navElements.length > 0 && mainElement) {
-    const skipLinks = target.querySelectorAll('a[href^="#"]');
-    const hasSkipToMain = Array.from(skipLinks).some(link => {
-      const href = link.getAttribute('href');
-      return href && (
-        href === '#main' ||
-        href === `#${mainElement.id}` ||
-        link.textContent?.toLowerCase().includes('skip to main') ||
-        link.textContent?.toLowerCase().includes('skip to content')
-      );
-    });
-
-    if (!hasSkipToMain) {
+  if (rules.includes('headings')) {
+    const h1s = target.querySelectorAll('h1');
+    if (h1s.length !== 1) {
       violations.push({
-        id: 'skip-link-missing',
-        impact: 'moderate',
-        nodes: 0,
-        help: 'Page with navigation should have skip links',
-        fix: 'Add a skip link to the main content area for keyboard users'
+        id: 'heading-structure', impact: 'moderate', nodes: h1s.length, help: 'Page should have exactly one h1'
       });
-    }
+    } else passes++;
   }
 
-  // Check that skip links are properly positioned (should be first focusable element)
-  const firstFocusable = target.querySelector('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
-  if (firstFocusable && firstFocusable.tagName === 'A') {
-    const href = firstFocusable.getAttribute('href');
-    if (!href?.startsWith('#')) {
+  if (rules.includes('forms')) {
+    const unlabeled = target.querySelectorAll('input:not([aria-label]):not([aria-labelledby])');
+    if (unlabeled.length > 0) {
       violations.push({
-        id: 'skip-link-not-first',
-        impact: 'minor',
-        nodes: 1,
-        help: 'Skip links should be the first focusable elements',
-        fix: 'Move skip links to the beginning of the document',
-        elements: [firstFocusable]
+        id: 'form-labels', impact: 'critical', nodes: unlabeled.length, help: 'Form inputs need labels'
       });
     }
+    passes += target.querySelectorAll('input[aria-label], input[aria-labelledby]').length;
   }
 
-  return { violations };
-}
-
-// Utility functions
-function calculateContrast(color1: string, color2: string): number {
-  // Convert colors to RGB values
-  const rgb1 = parseColor(color1);
-  const rgb2 = parseColor(color2);
-
-  if (!rgb1 || !rgb2) return 4.5; // Fallback if parsing fails
-
-  // Calculate relative luminance
-  const l1 = getRelativeLuminance(rgb1);
-  const l2 = getRelativeLuminance(rgb2);
-
-  // Calculate contrast ratio
-  const lighter = Math.max(l1, l2);
-  const darker = Math.min(l1, l2);
-
-  return (lighter + 0.05) / (darker + 0.05);
-}
-
-function parseColor(color: string): { r: number; g: number; b: number } | null {
-  // Handle rgb() format
-  const rgbMatch = color.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/);
-  if (rgbMatch && rgbMatch[1] && rgbMatch[2] && rgbMatch[3]) {
-    return {
-      r: parseInt(rgbMatch[1], 10),
-      g: parseInt(rgbMatch[2], 10),
-      b: parseInt(rgbMatch[3], 10)
-    };
-  }
-
-  // Handle hex format
-  const hexMatch = color.match(/^#([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i);
-  if (hexMatch && hexMatch[1] && hexMatch[2] && hexMatch[3]) {
-    return {
-      r: parseInt(hexMatch[1], 16),
-      g: parseInt(hexMatch[2], 16),
-      b: parseInt(hexMatch[3], 16)
-    };
-  }
-
-  // Handle named colors (basic set)
-  const namedColors: Record<string, { r: number; g: number; b: number }> = {
-    'black': { r: 0, g: 0, b: 0 },
-    'white': { r: 255, g: 255, b: 255 },
-    'red': { r: 255, g: 0, b: 0 },
-    'green': { r: 0, g: 128, b: 0 },
-    'blue': { r: 0, g: 0, b: 255 }
+  const report: AuditReport = {
+    violations, passes, timestamp: Date.now(),
+    url: typeof window !== 'undefined' ? window.location.href : ''
   };
 
-  return namedColors[color.toLowerCase()] || null;
-}
-
-function getRelativeLuminance(rgb: { r: number; g: number; b: number }): number {
-  const { r, g, b } = rgb;
-
-  // Convert to sRGB
-  const rsRGB = r / 255;
-  const gsRGB = g / 255;
-  const bsRGB = b / 255;
-
-  // Apply gamma correction
-  const rLinear = rsRGB <= 0.03928 ? rsRGB / 12.92 : Math.pow((rsRGB + 0.055) / 1.055, 2.4);
-  const gLinear = gsRGB <= 0.03928 ? gsRGB / 12.92 : Math.pow((gsRGB + 0.055) / 1.055, 2.4);
-  const bLinear = bsRGB <= 0.03928 ? bsRGB / 12.92 : Math.pow((bsRGB + 0.055) / 1.055, 2.4);
-
-  // Calculate relative luminance
-  return 0.2126 * rLinear + 0.7152 * gLinear + 0.0722 * bLinear;
-}
-
-function outputToConsole(report: AuditReport): void {
-  console.group('🔍 Accessibility Audit Results');
-  
-  if (report.violations.length === 0) {
-    console.log('✅ No accessibility violations found!');
-  } else {
-    console.log(`❌ Found ${report.violations.length} accessibility violations:`);
-    
-    report.violations.forEach(violation => {
-      const emoji = violation.impact === 'critical' ? '🚨' : 
-                   violation.impact === 'serious' ? '⚠️' : 
-                   violation.impact === 'moderate' ? '⚡' : 'ℹ️';
-      
-      console.group(`${emoji} ${violation.help}`);
-      console.log(`Impact: ${violation.impact}`);
-      console.log(`Fix: ${violation.fix}`);
-      if (violation.elements) {
-        console.log('Elements:', violation.elements);
-      }
-      console.groupEnd();
-    });
-  }
-  
-  console.log(`✅ ${report.passes} checks passed`);
-  if (report.incomplete > 0) {
-    console.log(`⚠️ ${report.incomplete} checks incomplete`);
-  }
-  
-  console.groupEnd();
-}
-
-function openReportInBrowser(report: AuditReport): void {
-  const html = generateHTMLReport(report);
-  const blob = new Blob([html], { type: 'text/html' });
-  const url = URL.createObjectURL(blob);
-
-  const newWindow = window.open(url, '_blank');
-  if (!newWindow) {
-    console.warn('Could not open report in new window. Please check popup blocker settings.');
-    // Fallback: download the report
-    const link = document.createElement('a');
-    link.href = url;
-    link.download = `proteus-a11y-report-${Date.now()}.html`;
-    link.click();
+  if (format === 'console' && violations.length > 0) {
+    console.group('🔍 A11y Audit Results');
+    violations.forEach(v => console.warn(`${v.impact}: ${v.help}`));
+    console.groupEnd();
   }
 
-  // Clean up the blob URL after a delay
-  setTimeout(() => URL.revokeObjectURL(url), 1000);
-}
-
-function generateHTMLReport(report: AuditReport): string {
-  const violationsList = report.violations.map(violation => `
-    <div class="violation violation--${violation.impact}">
-      <h3>${violation.help}</h3>
-      <p><strong>Impact:</strong> ${violation.impact}</p>
-      <p><strong>Fix:</strong> ${violation.fix}</p>
-      <p><strong>Affected elements:</strong> ${violation.nodes}</p>
-    </div>
-  `).join('');
-
-  return `
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>ProteusJS Accessibility Report</title>
-    <style>
-        body { font-family: system-ui, sans-serif; margin: 2rem; line-height: 1.6; }
-        .header { border-bottom: 2px solid #e5e7eb; padding-bottom: 1rem; margin-bottom: 2rem; }
-        .summary { background: #f3f4f6; padding: 1rem; border-radius: 8px; margin-bottom: 2rem; }
-        .violation { border-left: 4px solid #ef4444; padding: 1rem; margin-bottom: 1rem; background: #fef2f2; }
-        .violation--critical { border-color: #dc2626; background: #fef2f2; }
-        .violation--serious { border-color: #ea580c; background: #fff7ed; }
-        .violation--moderate { border-color: #d97706; background: #fffbeb; }
-        .violation--minor { border-color: #65a30d; background: #f7fee7; }
-        .violation h3 { margin-top: 0; color: #374151; }
-        .no-violations { text-align: center; color: #059669; font-size: 1.25rem; padding: 2rem; }
-    </style>
-</head>
-<body>
-    <div class="header">
-        <h1>🌊 ProteusJS Accessibility Report</h1>
-        <p>Generated on ${new Date(report.timestamp).toLocaleString()}</p>
-        <p>URL: ${report.url}</p>
-    </div>
-
-    <div class="summary">
-        <h2>Summary</h2>
-        <p><strong>Violations:</strong> ${report.violations.length}</p>
-        <p><strong>Checks passed:</strong> ${report.passes}</p>
-        <p><strong>Incomplete checks:</strong> ${report.incomplete}</p>
-    </div>
-
-    ${report.violations.length === 0 ?
-      '<div class="no-violations">✅ No accessibility violations found!</div>' :
-      `<h2>Violations</h2>${violationsList}`
-    }
-</body>
-</html>`;
+  return report;
 }
 
-// Export default object for convenience
-export default {
-  audit
-};
+export default { audit };