@afixt/test-utils 1.1.8 → 1.2.1

package/.claude/settings.local.json

@@ -19,7 +19,11 @@
       "Bash(npx vitest run:*)",
       "Bash(1)",
       "Bash(npm run test:playwright:css:*)",
-      "Bash(gh run list:*)"
+      "Bash(gh run list:*)",
+      "Bash(gh pr create:*)",
+      "Bash(git checkout:*)",
+      "Bash(git pull:*)",
+      "Bash(git merge:*)"
     ]
   },
   "enableAllProjectMcpServers": false

package/.github/workflows/pr-check.yml

@@ -0,0 +1,88 @@
+name: PR Check
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  validate-workflows:
+    name: Validate GitHub Actions Workflows
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Validate workflow syntax
+        run: |
+          echo "Validating GitHub Actions workflow files..."
+          errors=0
+
+          for f in .github/workflows/*.yml .github/workflows/*.yaml; do
+            [ -f "$f" ] || continue
+            echo "Checking $f..."
+
+            # Basic YAML syntax check
+            if ! python3 -c "import yaml; yaml.safe_load(open('$f'))" 2>/dev/null; then
+              echo "ERROR: Invalid YAML in $f"
+              errors=$((errors + 1))
+            fi
+
+            # Check for required 'on' and 'jobs' keys
+            if ! grep -q '^on:' "$f" && ! grep -q "^'on':" "$f" && ! grep -q '^"on":' "$f"; then
+              echo "WARNING: Missing 'on' trigger in $f"
+            fi
+
+            if ! grep -q '^jobs:' "$f"; then
+              echo "WARNING: Missing 'jobs' section in $f"
+            fi
+          done
+
+          if [ $errors -gt 0 ]; then
+            echo "Found $errors workflow file(s) with errors"
+            exit 1
+          fi
+
+          echo "All workflow files are valid"
+
+  ci-check:
+    name: CI Readiness Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Detect project type
+        id: detect
+        run: |
+          if [ -f "package.json" ]; then
+            echo "type=node" >> $GITHUB_OUTPUT
+          elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+            echo "type=python" >> $GITHUB_OUTPUT
+          else
+            echo "type=other" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup Node.js
+        if: steps.detect.outputs.type == 'node'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'lts/*'
+          cache: 'npm'
+
+      - name: Install dependencies
+        if: steps.detect.outputs.type == 'node'
+        run: npm ci --ignore-scripts
+        continue-on-error: true
+
+      - name: Run lint check
+        if: steps.detect.outputs.type == 'node'
+        run: npm run lint --if-present
+        continue-on-error: true
+
+      - name: Run tests
+        if: steps.detect.outputs.type == 'node'
+        run: npm test --if-present
+        continue-on-error: true

package/.github/workflows/security.yml

@@ -5,9 +5,6 @@ on:
     branches: [main, develop]
   pull_request:
     branches: [main, develop]
-  schedule:
-    # Run comprehensive scan every Sunday at midnight
-    - cron: '0 0 * * 0'
   workflow_dispatch:
 
 permissions:

package/eslint.config.mjs

@@ -53,7 +53,7 @@ export default [
     },
     {
         // ESM file overrides
-        files: ['**/*.mjs'],
+        files: ['**/*.mjs', 'vitest.config.js'],
         languageOptions: {
             sourceType: 'module',
         },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@afixt/test-utils",
-    "version": "1.1.8",
+    "version": "1.2.1",
     "description": "Various utilities for accessibility testing",
     "main": "src/index.js",
     "scripts": {
@@ -53,6 +53,7 @@
     "devDependencies": {
         "@eslint/js": "^9.39.2",
         "@playwright/test": "^1.57.0",
+        "@vitest/coverage-istanbul": "^3.2.4",
         "@vitest/coverage-v8": "^3.0.9",
         "clean-jsdoc-theme": "^4.3.0",
         "eslint": "^9.39.2",

package/src/constants.js

@@ -0,0 +1,231 @@
+/**
+ * @file Shared constants for accessibility testing
+ * @module constants
+ */
+
+/**
+ * CSS selector string for interactive elements.
+ * Matches native HTML interactive elements and ARIA widget roles.
+ * @type {string}
+ */
+const INTERACTIVE_SELECTOR = [
+    'a[href]',
+    'button',
+    'input:not([type="hidden"])',
+    'select',
+    'textarea',
+    '[tabindex]:not([tabindex="-1"])',
+    '[role="button"]',
+    '[role="link"]',
+    '[role="checkbox"]',
+    '[role="menuitem"]',
+    '[role="menuitemcheckbox"]',
+    '[role="menuitemradio"]',
+    '[role="tab"]',
+    '[role="switch"]',
+    '[role="option"]',
+    '[role="radio"]',
+    '[role="slider"]',
+    '[role="spinbutton"]',
+    '[role="textbox"]',
+    '[role="combobox"]',
+    '[role="listbox"]',
+    '[role="searchbox"]',
+    '[role="gridcell"]',
+    '[role="treeitem"]',
+].join(', ');
+
+/**
+ * CSS selector string for naturally focusable elements.
+ * These elements are focusable by default (unless disabled).
+ * @type {string}
+ */
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]',
+    'audio[controls]',
+    'video[controls]',
+    'embed',
+    'iframe',
+    'object',
+    '[contenteditable]:not([contenteditable="false"])',
+].join(', ');
+
+/**
+ * Labellable elements per HTML spec that can be associated with a <label>.
+ * @type {string[]}
+ */
+const LABELLABLE_ELEMENTS = [
+    'input',
+    'select',
+    'textarea',
+    'button',
+    'meter',
+    'output',
+    'progress',
+];
+
+/**
+ * Elements that validly support the alt attribute per HTML spec.
+ * @type {string[]}
+ */
+const VALID_ALT_ELEMENTS = ['IMG', 'AREA', 'INPUT', 'APPLET'];
+
+/**
+ * ISO 639-1 codes for right-to-left languages.
+ * @type {string[]}
+ */
+const RTL_LANGUAGES = [
+    'ar', // Arabic
+    'he', // Hebrew
+    'fa', // Persian/Farsi
+    'ur', // Urdu
+    'sd', // Sindhi
+    'yi', // Yiddish
+    'ps', // Pashto
+    'ku', // Kurdish (some dialects)
+    'ug', // Uyghur
+    'dv', // Divehi/Maldivian
+];
+
+/**
+ * Generic, non-descriptive, or meaningless frame/iframe titles.
+ * @type {string[]}
+ */
+const GENERIC_TITLES = ['iframe', 'frame', 'untitled', 'title', 'content', 'main', 'page'];
+
+/**
+ * Generic or useless table summaries commonly found in the wild.
+ * Merged from multiple detection contexts.
+ * @type {string[]}
+ */
+const GENERIC_SUMMARIES = [
+    'table',
+    'data',
+    'data table',
+    'information',
+    'content',
+    'main content',
+    'layout',
+    'layout table',
+    'for layout',
+    'table for layout purposes',
+    'structural table',
+    'this table is used for page layout',
+    'header',
+    'footer',
+    'navigation',
+    'nav',
+    'body',
+    'combobox',
+    'links design table',
+    'title and navigation',
+    'main heading',
+    'spacer',
+    'spacer table',
+    'menu',
+    'n/a',
+    'na',
+    'none',
+    'null',
+    'empty',
+    'blank',
+    'undefined',
+    'table summary',
+    'summary',
+];
+
+/**
+ * Phrases indicating structure-focused rather than content-focused table summary.
+ * @type {string[]}
+ */
+const STRUCTURE_PHRASES = [
+    'rows and columns',
+    'grid format',
+    'for display purposes',
+    'arranged in a grid',
+    'the following table shows',
+];
+
+/**
+ * Phrases indicating vague/rambling table summary content.
+ * @type {string[]}
+ */
+const VAGUE_PHRASES = [
+    'might find interesting',
+    'depending on their needs',
+    'users might find',
+    'may be useful',
+];
+
+/**
+ * Valid ARIA parent-child interactive role combinations per the WAI-ARIA spec.
+ * These composite widget patterns require interactive children by design.
+ * Key = parent role, Value = array of valid child roles.
+ * @type {Object.<string, string[]>}
+ */
+const VALID_ARIA_NESTING = {
+    listbox: ['option'],
+    menu: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'menu'],
+    menubar: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'menu'],
+    menuitem: ['menu', 'menubar'],
+    tablist: ['tab'],
+    tree: ['treeitem', 'group'],
+    treeitem: ['group', 'tree'],
+    grid: ['gridcell', 'row', 'rowgroup'],
+    row: ['gridcell', 'columnheader', 'rowheader', 'cell'],
+    rowgroup: ['row'],
+    radiogroup: ['radio'],
+    combobox: ['listbox', 'textbox', 'tree', 'grid', 'dialog'],
+};
+
+/**
+ * Thresholds for determining table complexity.
+ * @type {Object}
+ */
+const COMPLEXITY_THRESHOLDS = {
+    MAX_COLUMNS: 10,
+    MAX_HEADER_COLSPAN: 4,
+    MAX_ROWSPAN: 3,
+    MIN_HEADER_ROWS_FOR_COMPLEX: 3,
+};
+
+/**
+ * WCAG 2.5.5 minimum target size in CSS pixels.
+ * @type {number}
+ */
+const MIN_TARGET_SIZE = 44;
+
+/**
+ * Phrases that indicate a warning about new window/tab behavior.
+ * @type {string[]}
+ */
+const NEW_WINDOW_WARNINGS = [
+    'new window',
+    'new tab',
+    'opens in new',
+    'opens in a new',
+    'opens new',
+    'external link',
+    'external site',
+];
+
+module.exports = {
+    INTERACTIVE_SELECTOR,
+    FOCUSABLE_SELECTOR,
+    LABELLABLE_ELEMENTS,
+    VALID_ALT_ELEMENTS,
+    RTL_LANGUAGES,
+    GENERIC_TITLES,
+    GENERIC_SUMMARIES,
+    STRUCTURE_PHRASES,
+    VAGUE_PHRASES,
+    VALID_ARIA_NESTING,
+    COMPLEXITY_THRESHOLDS,
+    MIN_TARGET_SIZE,
+    NEW_WINDOW_WARNINGS,
+};

package/src/cssUtils.js

@@ -0,0 +1,77 @@
+/**
+ * @file CSS styling inspection utilities
+ * @module cssUtils
+ */
+
+const cssUtils = {
+    /**
+     * Check if an element's background is transparent/none.
+     * @param {CSSStyleDeclaration} style - The computed style
+     * @returns {boolean} True if background is transparent
+     */
+    hasTransparentBackground(style) {
+        const bg = style.backgroundColor;
+        const bgImage = style.backgroundImage;
+
+        if (bgImage && bgImage !== 'none') {
+            return false;
+        }
+
+        return bg === 'rgba(0, 0, 0, 0)' || bg === 'transparent' || bg === '';
+    },
+
+    /**
+     * Check if an element has no visible border.
+     * @param {CSSStyleDeclaration} style - The computed style
+     * @returns {boolean} True if no border
+     */
+    hasNoBorder(style) {
+        return style.borderStyle === 'none' || parseFloat(style.borderWidth) === 0;
+    },
+
+    /**
+     * Check if an element looks like regular text (no underline, background, or border).
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element looks like regular text
+     */
+    looksLikeText(element) {
+        const style = window.getComputedStyle(element);
+
+        const noUnderline = !style.textDecoration.toLowerCase().includes('underline');
+        const noBackground = cssUtils.hasTransparentBackground(style);
+        const noBorder = cssUtils.hasNoBorder(style);
+
+        return noUnderline && noBackground && noBorder;
+    },
+
+    /**
+     * Check if an element has link-like styling (underline).
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element has link-like styling
+     */
+    hasLinkStyling(element) {
+        const style = window.getComputedStyle(element);
+        return style.textDecoration.toLowerCase().includes('underline');
+    },
+
+    /**
+     * Check if an element has button-like styling (background/border with padding).
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element has button-like styling
+     */
+    hasButtonStyling(element) {
+        const style = window.getComputedStyle(element);
+
+        const hasBackground = !cssUtils.hasTransparentBackground(style);
+        const hasBorder = !cssUtils.hasNoBorder(style);
+        const hasPadding =
+            parseFloat(style.paddingTop) > 2 ||
+            parseFloat(style.paddingBottom) > 2 ||
+            parseFloat(style.paddingLeft) > 4 ||
+            parseFloat(style.paddingRight) > 4;
+
+        return (hasBackground || hasBorder) && hasPadding;
+    },
+};
+
+module.exports = cssUtils;