gbu-accessibility-package 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.0] - 2025-01-08
+
+### Added
+- **Enhanced Heading Structure Auto-Fix**: Automatic fixing of heading hierarchy issues with `--auto-fix-headings` option
+- **Improved Nested Controls Detection**: Better detection and fixing of nested interactive controls
+- **Advanced Test Cases**: New comprehensive test files for heading structure and nested controls
+- **Enhanced Alt Text Quality**: Improved context-aware alt text generation with better vocabulary support
+
+### Enhanced
+- **Heading Analysis**: More comprehensive detection of heading issues including empty headings, level skipping, and duplicates
+- **Interactive Controls**: Better handling of complex nested control scenarios
+- **Test Coverage**: Expanded demo files for better testing and validation
+- **Performance**: Optimized processing for large files and complex HTML structures
+
+### Fixed
+- **Heading Level Corrections**: Automatic correction of improper heading hierarchies
+- **Empty Heading Detection**: Better identification and handling of empty headings
+- **Control Nesting Issues**: Improved resolution of nested interactive control conflicts
+
 ## [3.2.0] - 2024-07-28
 
 ### Added

package/README-vi.md

@@ -18,7 +18,8 @@
 - 🔘 **Button Names** - Sửa buttons rỗng và input buttons không có tên
 - 🔗 **Link Names** - Sửa links rỗng và phát hiện text generic
 - 🏛️ **Landmarks** - Thêm main và navigation landmarks thiếu
-- 📑 **Phân tích Heading** - Phân tích cấu trúc heading với gợi ý (không tự động sửa)
+- 📑 **Phân tích và Sửa Heading** - Phân tích cấu trúc heading với tùy chọn tự động sửa `--auto-fix-headings`
+- 🎯 **Nested Controls Detection** - Phát hiện và sửa các control tương tác lồng nhau
 - 🔍 **Broken Links Detection** - Phát hiện liên kết bị hỏng và tài nguyên 404
 - 🧹 **Dọn dẹp Duplicate** - Loại bỏ role attributes trùng lặp
 
@@ -148,7 +149,8 @@ Chế độ sửa lỗi:
   --buttons-only           Sửa button names + dọn dẹp
   --links-only             Sửa link names + dọn dẹp
   --landmarks-only         Sửa landmarks + dọn dẹp
-  --headings-only          Phân tích cấu trúc heading (không tự động sửa)
+  --headings-only          Phân tích cấu trúc heading với tùy chọn tự động sửa
+  --auto-fix-headings      Bật tự động sửa lỗi heading structure
   --links-check            Kiểm tra liên kết bị hỏng và tài nguyên 404
   --cleanup-only           Chỉ dọn dẹp role attributes trùng lặp
 
@@ -178,6 +180,8 @@ gbu-a11y -l en ./public
 gbu-a11y --alt-only          # Sửa alt attributes + dọn dẹp
 gbu-a11y --forms-only        # Sửa form labels + dọn dẹp
 gbu-a11y --buttons-only      # Sửa button names + dọn dẹp
+gbu-a11y --headings-only     # Phân tích heading structure
+gbu-a11y --headings-only --auto-fix-headings  # Tự động sửa heading structure
 gbu-a11y --links-check       # Kiểm tra liên kết bị hỏng + dọn dẹp
 
 # Tính năng enhanced alt attribute
@@ -308,7 +312,12 @@ console.log("Hoàn thành sửa lỗi với enhanced features:", results);
 
 - **Lang attributes thiếu** → Phát hiện ngôn ngữ tự động
 - **Landmark thiếu** → Main và navigation landmarks
-- **Cấu trúc heading** → Phân tích và khuyến nghị
+- **Cấu trúc heading** → Phân tích và tự động sửa với `--auto-fix-headings`
+  - Sửa multiple h1 elements
+  - Sửa heading level skipping (h2 → h4)
+  - Thêm text cho empty headings
+  - Sửa duplicate headings
+- **Nested interactive controls** → Phát hiện và sửa controls lồng nhau
 - **Role attributes** → Gán role tuân thủ WCAG
 
 ### Kiểm tra liên kết

package/README.md

@@ -17,7 +17,8 @@
 - 🔘 **Button Names** - Fix empty buttons and input buttons without names
 - 🔗 **Link Names** - Fix empty links and detect generic link text
 - 🏛️ **Landmarks** - Add missing main and navigation landmarks
-- 📑 **Heading Analysis** - Analyze heading structure with suggestions (no auto-fix)
+- 📑 **Heading Analysis & Auto-Fix** - Analyze heading structure with optional auto-fix using `--auto-fix-headings`
+- 🎯 **Nested Controls Detection** - Detect and fix nested interactive controls
 - 🔍 **Broken Links Detection** - Detect broken links and 404 resources
 - 🧹 **Duplicate Cleanup** - Remove duplicate role attributes
 
@@ -145,7 +146,8 @@ Fix Modes:
   --buttons-only           Fix button names + cleanup
   --links-only             Fix link names + cleanup
   --landmarks-only         Fix landmarks + cleanup
-  --headings-only          Analyze heading structure (no auto-fix)
+  --headings-only          Analyze heading structure with optional auto-fix
+  --auto-fix-headings      Enable automatic heading structure fixes
   --links-check            Check for broken links and 404 resources
   --cleanup-only           Only cleanup duplicate role attributes
 
@@ -175,6 +177,8 @@ gbu-a11y -l en ./public
 gbu-a11y --alt-only          # Fix alt attributes + cleanup
 gbu-a11y --forms-only        # Fix form labels + cleanup
 gbu-a11y --buttons-only      # Fix button names + cleanup
+gbu-a11y --headings-only     # Analyze heading structure
+gbu-a11y --headings-only --auto-fix-headings  # Auto-fix heading structure
 gbu-a11y --links-check       # Check broken links + cleanup
 
 # Enhanced alt attribute features
@@ -298,7 +302,12 @@ console.log('Accessibility fixes completed with enhanced features:', results);
 ### Document Structure
 - **Missing lang attributes** → Automatic language detection
 - **Missing landmarks** → Main and navigation landmarks
-- **Heading structure** → Analysis and recommendations
+- **Heading structure** → Analysis and auto-fix with `--auto-fix-headings`
+  - Fix multiple h1 elements
+  - Fix heading level skipping (h2 → h4)
+  - Add text to empty headings
+  - Fix duplicate headings
+- **Nested interactive controls** → Detect and fix nested controls
 - **Role attributes** → WCAG-compliant role assignments
 
 ### Link Validation

package/cli.js

@@ -23,16 +23,21 @@ const options = {
   langOnly: false,
   roleOnly: false,
   formsOnly: false,
+  nestedOnly: false,
   buttonsOnly: false,
   linksOnly: false,
   landmarksOnly: false,
   headingsOnly: false,
+  dlOnly: false,
   brokenLinksOnly: false,
   // Enhanced alt options
   enhancedAlt: false,
   altCreativity: 'balanced', // conservative, balanced, creative
   includeEmotions: false,
-  strictAltChecking: false
+  strictAltChecking: false,
+  // Advanced features options
+  autoFixHeadings: false,
+  fixDescriptionLists: true
 };
 
 // Parse arguments
@@ -80,6 +85,9 @@ for (let i = 0; i < args.length; i++) {
     case '--forms-only':
       options.formsOnly = true;
       break;
+    case '--nested-only':
+      options.nestedOnly = true;
+      break;
     case '--buttons-only':
       options.buttonsOnly = true;
       break;
@@ -92,10 +100,19 @@ for (let i = 0; i < args.length; i++) {
     case '--headings-only':
       options.headingsOnly = true;
       break;
+    case '--dl-only':
+      options.dlOnly = true;
+      break;
     case '--links-check':
     case '--broken-links':
       options.brokenLinksOnly = true;
       break;
+    case '--auto-fix-headings':
+      options.autoFixHeadings = true;
+      break;
+    case '--no-fix-dl':
+      options.fixDescriptionLists = false;
+      break;
     case '--enhanced-alt':
       options.enhancedAlt = true;
       break;
@@ -221,14 +238,16 @@ async function main() {
     enhancedAltMode: options.enhancedAlt,
     altCreativity: options.altCreativity,
     includeEmotions: options.includeEmotions,
-    strictAltChecking: options.strictAltChecking
+    strictAltChecking: options.strictAltChecking,
+    autoFixHeadings: options.autoFixHeadings,
+    fixDescriptionLists: options.fixDescriptionLists
   });
 
   try {
     // Handle different modes - All modes now include cleanup
     if (options.cleanupOnly || options.altOnly || options.langOnly || options.roleOnly || 
-        options.formsOnly || options.buttonsOnly || options.linksOnly || options.landmarksOnly || 
-        options.headingsOnly || options.brokenLinksOnly) {
+        options.formsOnly || options.nestedOnly || options.buttonsOnly || options.linksOnly || options.landmarksOnly || 
+        options.headingsOnly || options.dlOnly || options.brokenLinksOnly) {
       // Individual modes - handle each separately, then run cleanup
     } else {
       // Default mode: Run comprehensive fix (all fixes including cleanup)
@@ -333,6 +352,24 @@ async function main() {
       showCompletionMessage(options, 'Form label fixes + cleanup');
       return;
       
+    } else if (options.nestedOnly) {
+      // Fix nested interactive controls + cleanup
+      console.log(chalk.blue('🎯 Running nested interactive controls fixes + cleanup...'));
+      const nestedResults = await fixer.fixNestedInteractiveControls(options.directory);
+      const nestedFixed = nestedResults.filter(r => r.status === 'fixed').length;
+      const totalNestedIssues = nestedResults.reduce((sum, r) => sum + (r.issues || 0), 0);
+      
+      console.log(chalk.green(`\n✅ Fixed nested interactive controls in ${nestedFixed} files (${totalNestedIssues} issues)`));
+      
+      // Run cleanup
+      console.log(chalk.blue('\n🧹 Running cleanup for duplicate role attributes...'));
+      const cleanupResults = await fixer.cleanupDuplicateRoles(options.directory);
+      const cleanupFixed = cleanupResults.filter(r => r.status === 'fixed').length;
+      console.log(chalk.green(`✅ Cleaned duplicate roles in ${cleanupFixed} files`));
+      
+      showCompletionMessage(options, 'Nested interactive controls fixes + cleanup');
+      return;
+      
     } else if (options.buttonsOnly) {
       // Fix button names + cleanup
       console.log(chalk.blue('🔘 Running button name fixes + cleanup...'));
@@ -388,15 +425,45 @@ async function main() {
       return;
       
     } else if (options.headingsOnly) {
-      // Analyze headings only (no fixes, no cleanup)
-      console.log(chalk.blue('📑 Running heading analysis only...'));
-      const headingResults = await fixer.analyzeHeadings(options.directory);
-      const totalSuggestions = headingResults.reduce((sum, r) => sum + (r.issues || 0), 0);
+      // Fix heading structure + cleanup
+      console.log(chalk.blue('📑 Running heading structure fixes + cleanup...'));
+      const headingResults = await fixer.fixHeadingStructure(options.directory);
+      const headingFixed = headingResults.filter(r => r.status === 'fixed').length;
+      const totalHeadingIssues = headingResults.reduce((sum, r) => sum + (r.issues || 0), 0);
+      const totalHeadingFixes = headingResults.reduce((sum, r) => sum + (r.fixes || 0), 0);
+      
+      console.log(chalk.green(`\n✅ Processed headings in ${headingResults.length} files (${totalHeadingIssues} issues found)`));
+      if (options.autoFixHeadings) {
+        console.log(chalk.green(`✅ Fixed ${totalHeadingFixes} heading issues automatically`));
+      } else {
+        console.log(chalk.gray('💡 Use --auto-fix-headings to enable automatic heading fixes'));
+      }
       
-      console.log(chalk.green(`\n✅ Analyzed headings in ${headingResults.length} files (${totalSuggestions} suggestions)`));
-      console.log(chalk.gray('💡 Heading issues require manual review and cannot be auto-fixed'));
+      // Run cleanup
+      console.log(chalk.blue('\n🧹 Running cleanup for duplicate role attributes...'));
+      const cleanupResults = await fixer.cleanupDuplicateRoles(options.directory);
+      const cleanupFixed = cleanupResults.filter(r => r.status === 'fixed').length;
+      console.log(chalk.green(`✅ Cleaned duplicate roles in ${cleanupFixed} files`));
+      
+      showCompletionMessage(options, 'Heading structure fixes + cleanup');
+      return;
+      
+    } else if (options.dlOnly) {
+      // Fix description lists + cleanup
+      console.log(chalk.blue('📋 Running description list fixes + cleanup...'));
+      const dlResults = await fixer.fixDescriptionLists(options.directory);
+      const dlFixed = dlResults.filter(r => r.status === 'fixed').length;
+      const totalDlIssues = dlResults.reduce((sum, r) => sum + (r.issues || 0), 0);
+      
+      console.log(chalk.green(`\n✅ Fixed description lists in ${dlFixed} files (${totalDlIssues} issues)`));
+      
+      // Run cleanup
+      console.log(chalk.blue('\n🧹 Running cleanup for duplicate role attributes...'));
+      const cleanupResults = await fixer.cleanupDuplicateRoles(options.directory);
+      const cleanupFixed = cleanupResults.filter(r => r.status === 'fixed').length;
+      console.log(chalk.green(`✅ Cleaned duplicate roles in ${cleanupFixed} files`));
       
-      showCompletionMessage(options, 'Heading analysis');
+      showCompletionMessage(options, 'Description list fixes + cleanup');
       return;
       
     } else if (options.brokenLinksOnly) {

package/demo/heading-structure-test.html

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="ja">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Heading Structure Test - Accessibility Issues</title>
+</head>
+<body>
+    <h1>Heading Structure Test Cases</h1>
+    
+    <!-- Test Case 1: Missing h1 (this will be converted from h2) -->
+    <h2>This should be h1</h2>
+    <p>Main content of the page</p>
+    
+    <!-- Test Case 2: Multiple h1 elements -->
+    <h1>First h1 (should stay)</h1>
+    <h1>Second h1 (should become h2)</h1>
+    <h1>Third h1 (should become h2)</h1>
+    
+    <!-- Test Case 3: Level skipping -->
+    <h2>Section heading</h2>
+    <h4>Subsection (skips h3 - should become h3)</h4>
+    <h6>Sub-subsection (skips h4, h5 - should become h4)</h6>
+    
+    <!-- Test Case 4: Empty headings -->
+    <h3></h3>
+    <h4>   </h4>
+    <h5><span></span></h5>
+    
+    <!-- Test Case 5: Duplicate headings -->
+    <h2>Products</h2>
+    <p>Some content about products</p>
+    <h2>Products</h2>
+    <p>More content about products</p>
+    
+    <!-- Test Case 6: Proper structure (should not be changed) -->
+    <h2>Proper Section</h2>
+    <h3>Proper Subsection</h3>
+    <h4>Proper Sub-subsection</h4>
+    <p>Content with proper heading hierarchy</p>
+    
+    <!-- Test Case 7: Complex nesting with issues -->
+    <h2>Services</h2>
+    <h5>Service 1 (should be h3)</h5>
+    <h6>Details (should be h4)</h6>
+    <h3>Service 2 (correct)</h3>
+    <h5>More details (should be h4)</h5>
+    
+    <!-- Test Case 8: Empty headings with context -->
+    <div class="section">
+        <h3></h3>
+        <p>This section talks about our company history and achievements.</p>
+    </div>
+    
+    <div class="product-info">
+        <h4>   </h4>
+        <p>Our flagship product offers innovative solutions for modern businesses.</p>
+    </div>
+</body>
+</html>

package/demo/nested-controls-test.html

@@ -0,0 +1,92 @@
+<!DOCTYPE html>
+<html lang="ja">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Nested Interactive Controls Test - Accessibility Issues</title>
+</head>
+<body>
+    <h1>Nested Interactive Controls Test Cases</h1>
+    
+    <!-- Test Case 1: div[role="button"] containing links (like in the axe error) -->
+    <div class="card-buttons" role="button">
+        <a href="https://business.mobile.rakuten.co.jp/solution/service/rakuten-ai-for-business/?scid=we_solution09_2504" class="btn btn-secondary" target="_blank" role="link">詳細を見る</a>
+        <a href="https://business.mobile.rakuten.co.jp/solution/ai/inquiry/?l=id=solution_ai_inquiry1&amp;scid=we_solution10_2504" class="btn btn-primary" target="_blank" role="link">お問い合わせ</a>
+    </div>
+    
+    <!-- Test Case 2: Button containing links -->
+    <button type="button" onclick="handleClick()">
+        <a href="/page1">Link inside button</a>
+        <span>Click me</span>
+    </button>
+    
+    <!-- Test Case 3: Link containing button -->
+    <a href="/page2">
+        <button type="button">Button inside link</button>
+    </a>
+    
+    <!-- Test Case 4: div[role="button"] containing input -->
+    <div role="button" tabindex="0" onclick="submit()">
+        <input type="text" placeholder="Search...">
+        <span>Submit</span>
+    </div>
+    
+    <!-- Test Case 5: Link containing select -->
+    <a href="/settings">
+        <select name="language">
+            <option value="ja">Japanese</option>
+            <option value="en">English</option>
+        </select>
+        Settings
+    </a>
+    
+    <!-- Test Case 6: Button containing textarea -->
+    <button type="submit">
+        <textarea name="comment" placeholder="Enter comment"></textarea>
+        <span>Send</span>
+    </button>
+    
+    <!-- Test Case 7: Multiple levels of nesting -->
+    <div role="button" tabindex="0">
+        <div class="container">
+            <a href="/nested">
+                <button type="button">Deeply nested</button>
+            </a>
+        </div>
+    </div>
+    
+    <!-- Test Case 8: div[role="button"] with tabindex containing interactive elements -->
+    <div role="button" tabindex="0" onclick="handleAction()">
+        <input type="checkbox" id="agree">
+        <label for="agree">I agree</label>
+        <a href="/terms">Terms</a>
+    </div>
+    
+    <!-- Test Case 9: Link containing details/summary -->
+    <a href="/info">
+        <details>
+            <summary>More info</summary>
+            <p>Details content</p>
+        </details>
+    </a>
+    
+    <!-- Test Case 10: Form elements nested in buttons -->
+    <button type="button" class="form-button">
+        <input type="radio" name="choice" value="1">
+        <input type="radio" name="choice" value="2">
+        <span>Choose option</span>
+    </button>
+    
+    <!-- Test Case 11: Correct structure (should not be flagged) -->
+    <div class="card-buttons">
+        <a href="/page1" class="btn btn-secondary">詳細を見る</a>
+        <a href="/page2" class="btn btn-primary">お問い合わせ</a>
+    </div>
+    
+    <!-- Test Case 12: Another correct structure -->
+    <button type="button" onclick="handleClick()">
+        <span>Click me</span>
+        <i class="icon"></i>
+    </button>
+</body>
+</html>