@tanstack/devtools-a11y 0.0.1 → 0.1.1

package/src/core/utils/export-audit.uitls.ts

@@ -0,0 +1,180 @@
+import type { A11yAuditResult, ExportOptions } from '../types/types'
+
+/**
+ * Export audit results to JSON format
+ */
+export function exportToJson(
+  result: A11yAuditResult,
+  _options: Partial<ExportOptions> = {},
+): string {
+  const exportData = {
+    meta: {
+      exportedAt: new Date().toISOString(),
+      url: result.url,
+      auditTimestamp: result.timestamp,
+      duration: result.duration,
+      context: result.context,
+    },
+    summary: result.summary,
+    issues: result.issues.map((issue) => ({
+      id: issue.id,
+      ruleId: issue.ruleId,
+      impact: issue.impact,
+      message: issue.message,
+      help: issue.help,
+      helpUrl: issue.helpUrl,
+      wcagTags: issue.wcagTags,
+      nodes: issue.nodes.map((node) => ({
+        selector: node.selector,
+        html: node.html,
+        failureSummary: node.failureSummary,
+      })),
+    })),
+  }
+
+  return JSON.stringify(exportData, null, 2)
+}
+
+/**
+ * Export audit results to CSV format
+ */
+export function exportToCsv(
+  result: A11yAuditResult,
+  _options: Partial<ExportOptions> = {},
+): string {
+  const headers = [
+    'Rule ID',
+    'Impact',
+    'Message',
+    'Help URL',
+    'WCAG Tags',
+    'Selector',
+    'HTML',
+  ]
+
+  const rows: Array<Array<string>> = []
+
+  for (const issue of result.issues) {
+    for (const node of issue.nodes) {
+      rows.push([
+        issue.ruleId,
+        issue.impact,
+        issue.message.replace(/"/g, '""'),
+        issue.helpUrl,
+        issue.wcagTags.join('; '),
+        node.selector,
+        node.html.replace(/"/g, '""'),
+      ])
+    }
+  }
+
+  return [
+    headers.map((h) => `"${h}"`).join(','),
+    ...rows.map((row) => row.map((cell) => `"${cell}"`).join(',')),
+  ].join('\n')
+}
+
+/**
+ * Download a file with the given content
+ */
+function downloadFile(
+  content: string,
+  filename: string,
+  mimeType: string,
+): void {
+  const blob = new Blob([content], { type: mimeType })
+  const url = URL.createObjectURL(blob)
+  const link = document.createElement('a')
+  link.href = url
+  link.download = filename
+  document.body.appendChild(link)
+  link.click()
+  document.body.removeChild(link)
+  URL.revokeObjectURL(url)
+}
+
+/**
+ * Export audit results and trigger download
+ */
+export function exportAuditResults(
+  result: A11yAuditResult,
+  options: ExportOptions,
+): void {
+  const { format, filename } = options
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const defaultFilename = `a11y-audit-${timestamp}`
+
+  if (format === 'json') {
+    const content = exportToJson(result, options)
+    downloadFile(
+      content,
+      `${filename || defaultFilename}.json`,
+      'application/json',
+    )
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  } else if (format === 'csv') {
+    const content = exportToCsv(result, options)
+    downloadFile(content, `${filename || defaultFilename}.csv`, 'text/csv')
+  }
+}
+
+/**
+ * Generate a summary report as a formatted string
+ */
+export function generateSummaryReport(result: A11yAuditResult): string {
+  const { summary } = result
+
+  const lines = [
+    '='.repeat(50),
+    'ACCESSIBILITY AUDIT REPORT',
+    '='.repeat(50),
+    '',
+    `URL: ${result.url}`,
+    `Date: ${new Date(result.timestamp).toLocaleString()}`,
+    `Duration: ${result.duration.toFixed(2)}ms`,
+    '',
+    '-'.repeat(50),
+    'SUMMARY',
+    '-'.repeat(50),
+    '',
+    `Total Issues: ${summary.total}`,
+    `  - Critical: ${summary.critical}`,
+    `  - Serious: ${summary.serious}`,
+    `  - Moderate: ${summary.moderate}`,
+    `  - Minor: ${summary.minor}`,
+    '',
+    `Passing Rules: ${summary.passes}`,
+    `Incomplete Checks: ${summary.incomplete}`,
+    '',
+  ]
+
+  if (result.issues.length > 0) {
+    lines.push('-'.repeat(50))
+    lines.push('ISSUES')
+    lines.push('-'.repeat(50))
+    lines.push('')
+
+    const issuesByImpact = {
+      critical: result.issues.filter((i) => i.impact === 'critical'),
+      serious: result.issues.filter((i) => i.impact === 'serious'),
+      moderate: result.issues.filter((i) => i.impact === 'moderate'),
+      minor: result.issues.filter((i) => i.impact === 'minor'),
+    }
+
+    for (const [impact, issues] of Object.entries(issuesByImpact)) {
+      if (issues.length > 0) {
+        lines.push(`[${impact.toUpperCase()}]`)
+        for (const issue of issues) {
+          lines.push(`  - ${issue.ruleId}: ${issue.message}`)
+          lines.push(`    Selector: ${issue.nodes[0]?.selector}`)
+          lines.push(`    Learn more: ${issue.helpUrl}`)
+          lines.push('')
+        }
+      }
+    }
+  }
+
+  lines.push('='.repeat(50))
+
+  return lines.join('\n')
+}

package/src/core/utils/ui.utils.ts

@@ -0,0 +1,483 @@
+// types
+import type {
+  A11yIssue,
+  RuleSetPreset,
+  SeverityThreshold,
+} from '../types/types'
+
+export function scrollToElement(selector: string): boolean {
+  try {
+    const element = document.querySelector(selector)
+    if (element) {
+      element.scrollIntoView({
+        behavior: 'smooth',
+        block: 'start',
+        inline: 'nearest',
+      })
+      return true
+    }
+  } catch (error) {
+    console.warn('[A11y Panel] Could not scroll to element:', selector, error)
+  }
+  return false
+}
+
+const HIGHLIGHT_CLASS = 'tsd-a11y-highlight'
+const HIGHLIGHT_STYLE_ID = 'tsd-a11y-highlight-styles'
+const TOOLTIP_CLASS = 'tsd-a11y-tooltip'
+
+// Track active tooltips and their target elements for scroll updates
+const activeTooltips = new Map<HTMLElement, Element>()
+let scrollHandler: (() => void) | null = null
+
+// Tooltip height (padding + font size + some buffer)
+const TOOLTIP_HEIGHT = 28
+
+/**
+ * Severity levels mapped to numeric values for comparison (higher = more severe)
+ */
+export const SEVERITY_ORDER: Record<SeverityThreshold, number> = {
+  critical: 4,
+  serious: 3,
+  moderate: 2,
+  minor: 1,
+}
+
+/**
+ * Selectors for devtools elements that should never be highlighted
+ */
+const DEVTOOLS_SELECTORS = [
+  '[data-testid="tanstack_devtools"]',
+  '[data-devtools]',
+  '[data-devtools-panel]',
+  '[data-a11y-overlay]',
+]
+
+/**
+ * Check if an element is inside the devtools panel
+ */
+function isInsideDevtools(element: Element): boolean {
+  for (const selector of DEVTOOLS_SELECTORS) {
+    if (element.closest(selector)) {
+      return true
+    }
+  }
+  return false
+}
+
+export const SEVERITY_LABELS: Record<SeverityThreshold, string> = {
+  critical: 'Critical',
+  serious: 'Serious',
+  moderate: 'Moderate',
+  minor: 'Minor',
+}
+
+export const RULE_SET_LABELS: Record<RuleSetPreset, string> = {
+  wcag2a: 'WCAG 2.0 A',
+  wcag2aa: 'WCAG 2.0 AA',
+  wcag21aa: 'WCAG 2.1 AA',
+  wcag22aa: 'WCAG 2.2 AA',
+  section508: 'Section 508',
+  'best-practice': 'Best Practice',
+  all: 'All Rules',
+}
+
+/**
+ * Color scheme for different severity levels
+ */
+const SEVERITY_COLORS: Record<
+  SeverityThreshold,
+  { border: string; bg: string; text: string }
+> = {
+  critical: {
+    border: '#dc2626',
+    bg: 'rgba(220, 38, 38, 0.15)',
+    text: '#dc2626',
+  },
+  serious: {
+    border: '#ea580c',
+    bg: 'rgba(234, 88, 12, 0.15)',
+    text: '#ea580c',
+  },
+  moderate: {
+    border: '#ca8a04',
+    bg: 'rgba(202, 138, 4, 0.15)',
+    text: '#ca8a04',
+  },
+  minor: { border: '#2563eb', bg: 'rgba(37, 99, 235, 0.15)', text: '#2563eb' },
+}
+
+/**
+ * Inject overlay styles into the document
+ */
+function injectStyles(): void {
+  if (document.getElementById(HIGHLIGHT_STYLE_ID)) {
+    return
+  }
+
+  const style = document.createElement('style')
+  style.id = HIGHLIGHT_STYLE_ID
+  // Highlights use outline which doesn't affect layout
+  // Tooltips use fixed positioning to avoid layout shifts
+  style.textContent = `
+    .${HIGHLIGHT_CLASS}--critical {
+      outline: 3px solid ${SEVERITY_COLORS.critical.border} !important;
+      outline-offset: 2px !important;
+      background-color: ${SEVERITY_COLORS.critical.bg} !important;
+    }
+
+    .${HIGHLIGHT_CLASS}--serious {
+      outline: 3px solid ${SEVERITY_COLORS.serious.border} !important;
+      outline-offset: 2px !important;
+      background-color: ${SEVERITY_COLORS.serious.bg} !important;
+    }
+
+    .${HIGHLIGHT_CLASS}--moderate {
+      outline: 2px solid ${SEVERITY_COLORS.moderate.border} !important;
+      outline-offset: 2px !important;
+      background-color: ${SEVERITY_COLORS.moderate.bg} !important;
+    }
+
+    .${HIGHLIGHT_CLASS}--minor {
+      outline: 2px dashed ${SEVERITY_COLORS.minor.border} !important;
+      outline-offset: 2px !important;
+      background-color: ${SEVERITY_COLORS.minor.bg} !important;
+    }
+
+    .${TOOLTIP_CLASS} {
+      position: fixed;
+      padding: 4px 8px;
+      border-radius: 4px;
+      font-size: 11px;
+      font-weight: 600;
+      font-family: system-ui, -apple-system, sans-serif;
+      white-space: nowrap;
+      z-index: 99990;
+      pointer-events: none;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+      max-width: 90vw;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .${TOOLTIP_CLASS}--critical {
+      background: ${SEVERITY_COLORS.critical.border};
+      color: white;
+    }
+
+    .${TOOLTIP_CLASS}--serious {
+      background: ${SEVERITY_COLORS.serious.border};
+      color: white;
+    }
+
+    .${TOOLTIP_CLASS}--moderate {
+      background: ${SEVERITY_COLORS.moderate.border};
+      color: white;
+    }
+
+    .${TOOLTIP_CLASS}--minor {
+      background: ${SEVERITY_COLORS.minor.border};
+      color: white;
+    }
+  `
+  document.head.appendChild(style)
+}
+
+/**
+ * Calculate optimal tooltip position, ensuring it's always visible in viewport
+ */
+function calculateTooltipPosition(
+  targetElement: Element,
+  tooltip: HTMLElement,
+): { top: number; left: number; flipped: boolean } {
+  const rect = targetElement.getBoundingClientRect()
+  const tooltipHeight = TOOLTIP_HEIGHT
+  const gap = 4 // Small gap between tooltip and element
+  const viewportPadding = 8 // Minimum distance from viewport edge
+
+  // Default: position above the element
+  let top = rect.top - tooltipHeight - gap
+  let flipped = false
+
+  // If tooltip would be above viewport, we need to find a visible position
+  if (top < viewportPadding) {
+    // Try positioning below the element's top edge (inside the element but visible)
+    const belowTop = rect.top + gap + viewportPadding
+
+    // If the element's bottom is within the viewport, position below the element
+    if (rect.bottom + gap + tooltipHeight < window.innerHeight) {
+      top = rect.bottom + gap
+      flipped = true
+    }
+    // Otherwise, position at the top of the viewport (for large elements like <main>)
+    else if (belowTop + tooltipHeight < window.innerHeight) {
+      top = belowTop
+      flipped = true
+    }
+    // Fallback: just keep it at the top of the viewport
+    else {
+      top = viewportPadding
+      flipped = true
+    }
+  }
+
+  // Also handle horizontal overflow - keep tooltip within viewport
+  let left = rect.left
+  const tooltipWidth = tooltip.offsetWidth || 150 // Estimate if not yet rendered
+  if (left + tooltipWidth > window.innerWidth) {
+    left = Math.max(
+      viewportPadding,
+      window.innerWidth - tooltipWidth - viewportPadding,
+    )
+  }
+  if (left < viewportPadding) {
+    left = viewportPadding
+  }
+
+  return { top, left, flipped }
+}
+
+/**
+ * Update all tooltip positions based on their target elements
+ */
+function updateTooltipPositions(): void {
+  activeTooltips.forEach((targetElement, tooltip) => {
+    const { top, left } = calculateTooltipPosition(targetElement, tooltip)
+    tooltip.style.top = `${top}px`
+    tooltip.style.left = `${left}px`
+  })
+}
+
+/**
+ * Start listening for scroll events to update tooltip positions
+ */
+function startScrollListener(): void {
+  if (scrollHandler) return
+
+  scrollHandler = () => {
+    requestAnimationFrame(updateTooltipPositions)
+  }
+
+  window.addEventListener('scroll', scrollHandler, true) // capture phase to catch all scrolls
+}
+
+/**
+ * Stop listening for scroll events
+ */
+function stopScrollListener(): void {
+  if (scrollHandler) {
+    window.removeEventListener('scroll', scrollHandler, true)
+    scrollHandler = null
+  }
+}
+
+/**
+ * Issue info for tooltip display
+ */
+interface TooltipIssue {
+  ruleId: string
+  impact: SeverityThreshold
+}
+
+/**
+ * Create a tooltip element for issues and position it above the target element
+ */
+function createTooltip(
+  issues: Array<TooltipIssue>,
+  targetElement: Element,
+): HTMLElement | null {
+  if (issues.length === 0) {
+    return null
+  }
+
+  // Sort issues by severity (most severe first)
+  const sortedIssues = [...issues].sort(
+    (a, b) => SEVERITY_ORDER[b.impact] - SEVERITY_ORDER[a.impact],
+  )
+
+  const firstIssue = sortedIssues[0]
+  if (!firstIssue) {
+    return null
+  }
+
+  const mostSevere = firstIssue.impact
+  const tooltip = document.createElement('div')
+  tooltip.className = `${TOOLTIP_CLASS} ${TOOLTIP_CLASS}--${mostSevere}`
+
+  // Build tooltip content showing all issues
+  if (sortedIssues.length === 1) {
+    tooltip.textContent = `${mostSevere.toUpperCase()}: ${firstIssue.ruleId}`
+  } else {
+    // Multiple issues - show count and list
+    const issueList = sortedIssues
+      .map(
+        (issue) => `${issue.impact.charAt(0).toUpperCase()}: ${issue.ruleId}`,
+      )
+      .join(' | ')
+    tooltip.textContent = `${sortedIssues.length} issues: ${issueList}`
+  }
+
+  // Mark as overlay element so it's excluded from a11y scans
+  tooltip.setAttribute('data-a11y-overlay', 'true')
+
+  // Track this tooltip for scroll updates (need to add before positioning)
+  activeTooltips.set(tooltip, targetElement)
+
+  // Start scroll listener if not already running
+  if (activeTooltips.size === 1) {
+    startScrollListener()
+  }
+
+  // Position the tooltip - will flip below element if above viewport
+  const { top, left } = calculateTooltipPosition(targetElement, tooltip)
+  tooltip.style.top = `${top}px`
+  tooltip.style.left = `${left}px`
+
+  return tooltip
+}
+
+/**
+ * Highlight a single element with the specified severity
+ */
+export function highlightElement(
+  selector: string,
+  impact: SeverityThreshold = 'serious',
+  options: { showTooltip?: boolean; ruleId?: string } = {},
+): void {
+  const { showTooltip = true, ruleId } = options
+
+  try {
+    injectStyles()
+
+    const elements = document.querySelectorAll(selector)
+    if (elements.length === 0) {
+      console.warn(`[A11y Overlay] No elements found for selector: ${selector}`)
+      return
+    }
+
+    let highlightedCount = 0
+    elements.forEach((el) => {
+      // Skip elements inside devtools
+      if (isInsideDevtools(el)) {
+        return
+      }
+
+      el.classList.add(HIGHLIGHT_CLASS, `${HIGHLIGHT_CLASS}--${impact}`)
+
+      // Add tooltip to first highlighted element only
+      if (showTooltip && highlightedCount === 0 && ruleId) {
+        const tooltip = createTooltip([{ ruleId, impact }], el)
+        if (tooltip) {
+          document.body.appendChild(tooltip)
+        }
+      }
+
+      highlightedCount++
+    })
+
+    if (highlightedCount > 0) {
+      console.log(
+        `[A11y Overlay] Highlighted ${highlightedCount} element(s) with selector: ${selector}`,
+      )
+    }
+  } catch (error) {
+    console.error('[A11y Overlay] Error highlighting element:', error)
+  }
+}
+
+/**
+ * Highlight all elements with issues.
+ * Shows all issues per element in the tooltip, using the most severe for highlighting.
+ */
+export function highlightAllIssues(issues: Array<A11yIssue>): void {
+  injectStyles()
+  clearHighlights()
+
+  // Track ALL issues for each selector
+  // Map: selector -> Array<{ ruleId, impact }>
+  const selectorIssues = new Map<string, Array<TooltipIssue>>()
+
+  // Collect all issues per selector
+  for (const issue of issues) {
+    for (const node of issue.nodes) {
+      const selector = node.selector
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      const impact = issue.impact ?? 'minor'
+
+      const existing = selectorIssues.get(selector) || []
+      // Avoid duplicate rule IDs for the same selector
+      if (!existing.some((e) => e.ruleId === issue.ruleId)) {
+        existing.push({ ruleId: issue.ruleId, impact })
+        selectorIssues.set(selector, existing)
+      }
+    }
+  }
+
+  // Highlight each selector with its most severe issue, but show all in tooltip
+  for (const [selector, issueList] of selectorIssues) {
+    // Skip empty lists (shouldn't happen, but guards against undefined)
+    if (issueList.length === 0) {
+      continue
+    }
+
+    // Find most severe impact for highlighting
+    const mostSevereImpact = issueList.reduce((max, issue) =>
+      SEVERITY_ORDER[issue.impact] > SEVERITY_ORDER[max.impact] ? issue : max,
+    ).impact
+
+    try {
+      const elements = document.querySelectorAll(selector)
+      if (elements.length === 0) {
+        continue
+      }
+
+      let highlightedCount = 0
+      elements.forEach((el) => {
+        // Skip elements inside devtools
+        if (isInsideDevtools(el)) {
+          return
+        }
+
+        el.classList.add(
+          HIGHLIGHT_CLASS,
+          `${HIGHLIGHT_CLASS}--${mostSevereImpact}`,
+        )
+
+        // Add tooltip to first highlighted element only, showing ALL issues
+        if (highlightedCount === 0) {
+          const tooltip = createTooltip(issueList, el)
+          if (tooltip) {
+            document.body.appendChild(tooltip)
+          }
+        }
+
+        highlightedCount++
+      })
+    } catch (error) {
+      console.error('[A11y Overlay] Error highlighting element:', error)
+    }
+  }
+}
+
+/**
+ * Clear all highlights from the page
+ */
+export function clearHighlights(): void {
+  // Remove highlight classes
+  const highlighted = document.querySelectorAll(`.${HIGHLIGHT_CLASS}`)
+  highlighted.forEach((el) => {
+    el.classList.remove(
+      HIGHLIGHT_CLASS,
+      `${HIGHLIGHT_CLASS}--critical`,
+      `${HIGHLIGHT_CLASS}--serious`,
+      `${HIGHLIGHT_CLASS}--moderate`,
+      `${HIGHLIGHT_CLASS}--minor`,
+    )
+  })
+
+  // Remove tooltips and clear tracking
+  const tooltips = document.querySelectorAll(`.${TOOLTIP_CLASS}`)
+  tooltips.forEach((el) => el.remove())
+  activeTooltips.clear()
+  stopScrollListener()
+}

package/src/react/A11yDevtools.ts

@@ -0,0 +1,12 @@
+import { createReactPanel } from '@tanstack/devtools-utils/react'
+import { A11yDevtoolsCore } from '../core'
+
+// type
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/react'
+
+export interface A11yDevtoolsReactInit extends DevtoolsPanelProps {}
+
+const [A11yDevtoolsPanel, A11yDevtoolsPanelNoOp] =
+  createReactPanel(A11yDevtoolsCore)
+
+export { A11yDevtoolsPanel, A11yDevtoolsPanelNoOp }

package/src/react/index.ts

@@ -0,0 +1,16 @@
+'use client'
+
+import * as Devtools from './A11yDevtools'
+import * as plugin from './plugin'
+
+export const A11yDevtoolsPanel =
+  process.env.NODE_ENV !== 'development'
+    ? Devtools.A11yDevtoolsPanelNoOp
+    : Devtools.A11yDevtoolsPanel
+
+export const a11yDevtoolsPlugin =
+  process.env.NODE_ENV !== 'development'
+    ? plugin.a11yDevtoolsNoOpPlugin
+    : plugin.a11yDevtoolsPlugin
+
+export type { A11yDevtoolsReactInit } from './A11yDevtools'

package/src/react/plugin.ts

@@ -0,0 +1,9 @@
+import { createReactPlugin } from '@tanstack/devtools-utils/react'
+import { A11yDevtoolsPanel } from './A11yDevtools'
+
+const [a11yDevtoolsPlugin, a11yDevtoolsNoOpPlugin] = createReactPlugin({
+  name: 'TanStack A11y',
+  Component: A11yDevtoolsPanel,
+})
+
+export { a11yDevtoolsPlugin, a11yDevtoolsNoOpPlugin }

package/src/react/production/A11yDevtools.ts

@@ -0,0 +1,11 @@
+import { createReactPanel } from '@tanstack/devtools-utils/react'
+import { A11yDevtoolsCore } from '../../core'
+
+// type
+import type { DevtoolsPanelProps } from '@tanstack/devtools-utils/react'
+
+export interface A11yDevtoolsReactInit extends DevtoolsPanelProps {}
+
+const [A11yDevtoolsPanel] = createReactPanel(A11yDevtoolsCore)
+
+export { A11yDevtoolsPanel }