wip: implement live monitoring feature with customizable delay and enhance configuration options

Author: LadyBluenotes

docs/plugins/a11y.md

@@ -81,44 +81,42 @@ This makes it easy to locate and inspect issues directly on the page.
 
 ## Panel Configuration
 
-The `A11yDevtoolsPanel` component accepts the following props:
+`A11yDevtoolsPanel` is React-first and takes an `options` prop that matches `A11yPluginOptions`.
 
 ```tsx
+import type { A11yPluginOptions } from '@tanstack/devtools-a11y'
+
 interface A11yDevtoolsPanelProps {
-  /** Default WCAG standard to use */
-  defaultStandard?: 'wcag2a' | 'wcag2aa' | 'wcag2aaa' | 'wcag21a' | 'wcag21aa' | 'wcag21aaa' | 'wcag22aa' | 'section508' | 'best-practice'
-  
-  /** Enable live monitoring by default */
-  defaultLiveMonitoring?: boolean
-  
-  /** Show overlays by default */
-  defaultShowOverlays?: boolean
-  
-  /** Enable scoped scanning by default */
-  defaultScopedMode?: boolean
-  
-  /** Auto-scan on panel mount */
-  autoScan?: boolean
-  
-  /** Custom axe-core rules to include */
-  includeRules?: string[]
-  
-  /** Custom axe-core rules to exclude */
-  excludeRules?: string[]
-  
-  /** CSS selectors to exclude from scanning */
-  excludeSelectors?: string[]
+  options?: A11yPluginOptions
+  theme?: 'light' | 'dark'
 }
 ```
 
+Common `options` fields:
+
+- `threshold`: minimum impact level to show
+- `ruleSet`: rule preset (`'wcag2a' | 'wcag2aa' | 'wcag21aa' | 'wcag22aa' | 'section508' | 'best-practice' | 'all'`)
+- `disabledRules`: rule IDs to ignore
+- `showOverlays`: highlight issues in the page
+- `runOnMount`: auto-scan when panel mounts
+- `persistSettings`: store config in localStorage
+- `liveMonitoring`: watch DOM mutations and re-scan automatically
+- `liveMonitoringDelay`: debounce delay (ms)
+
 ### Example with Configuration
 
 ```tsx
 <A11yDevtoolsPanel
-  defaultStandard="wcag21aa"
-  defaultLiveMonitoring={true}
-  autoScan={true}
-  excludeSelectors={['.third-party-widget', '[data-testid="skip-a11y"]']}
+  theme={theme}
+  options={{
+    ruleSet: 'wcag21aa',
+    threshold: 'moderate',
+    runOnMount: true,
+    showOverlays: true,
+    liveMonitoring: true,
+    liveMonitoringDelay: 1000,
+    disabledRules: ['color-contrast'],
+  }}
 />
 ```
 
@@ -201,33 +199,32 @@ function MyComponent() {
 
 ## Vanilla JavaScript API
 
-For non-React applications, use the vanilla JavaScript plugin:
+For non-React applications, `createA11yPlugin()` exposes a small programmatic API in addition to the TanStack Devtools `render()` integration:
 
 ```ts
 import { createA11yPlugin } from '@tanstack/devtools-a11y'
 
 const plugin = createA11yPlugin({
-  standard: 'wcag21aa',
+  ruleSet: 'wcag21aa',
   liveMonitoring: true,
   showOverlays: true,
 })
 
 // Run a scan
-const result = await plugin.scan()
+const result = await plugin.scan?.()
 
-// Start live monitoring
-plugin.startLiveMonitoring()
-
-// Stop live monitoring
-plugin.stopLiveMonitoring()
-
-// Subscribe to scan results
-plugin.onScan((result) => {
-  console.log('Issues found:', result.issues.length)
+// Subscribe to scan results (manual or live)
+const unsubscribe = plugin.onScan?.((next) => {
+  console.log('Issues found:', next.issues.length)
 })
 
+// Control live monitoring
+plugin.startLiveMonitoring?.()
+plugin.stopLiveMonitoring?.()
+
 // Clean up
-plugin.destroy()
+unsubscribe?.()
+plugin.destroy?.()
 ```
 
 ## Export Formats

examples/react/basic/package.json

@@ -22,7 +22,6 @@
     "zod": "^4.1.11"
   },
   "devDependencies": {
-    "@tanstack/devtools-a11y": "workspace:^",
     "@tanstack/devtools-ui": "0.4.4",
     "@tanstack/devtools-vite": "0.4.1",
     "@tanstack/react-form-devtools": "^0.1.7",

examples/react/basic/vite.config.ts

@@ -1,4 +1,3 @@
-import path from 'node:path'
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import { devtools } from '@tanstack/devtools-vite'
@@ -20,18 +19,6 @@ export default defineConfig({
       // },
     }),
   ],
-  resolve: {
-    alias: {
-      '@tanstack/devtools-a11y/react': path.resolve(
-        __dirname,
-        '../../../packages/devtools-a11y/src/react',
-      ),
-      '@tanstack/devtools-a11y': path.resolve(
-        __dirname,
-        '../../../packages/devtools-a11y/src',
-      ),
-    },
-  },
   build: {
     sourcemap: true,
   },

packages/devtools-a11y/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/devtools-a11y",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Accessibility auditing plugin for TanStack Devtools powered by axe-core",
   "author": "TanStack",
   "license": "MIT",

packages/devtools-a11y/src/config.ts

@@ -8,12 +8,13 @@ const STORAGE_KEY = 'tanstack-devtools-a11y-config'
 export const DEFAULT_CONFIG: Required<A11yPluginOptions> = {
   threshold: 'serious',
   runOnMount: false,
+  liveMonitoring: false,
+  liveMonitoringDelay: 1000,
   ruleSet: 'wcag21aa',
   showOverlays: true,
   persistSettings: true,
   engine: 'axe-core',
   disabledRules: [],
-  rootSelector: '',
 }
 
 /**

packages/devtools-a11y/src/live-monitoring.ts

@@ -0,0 +1,164 @@
+import { diffAuditResults, filterByThreshold, runAudit } from './scanner'
+import type {
+  A11yAuditOptions,
+  A11yAuditResult,
+  A11yIssue,
+  SeverityThreshold,
+} from './types'
+
+export interface LiveMonitoringOptions {
+  delay: number
+  threshold: SeverityThreshold
+  disabledRules: Array<string>
+  context?: A11yAuditOptions['context']
+}
+
+export interface LiveMonitoringCallbacks {
+  onResults: (result: A11yAuditResult) => void
+  onDiff?: (diff: {
+    newIssues: Array<A11yIssue>
+    resolvedIssues: Array<A11yIssue>
+  }) => void
+}
+
+export function createLiveMonitoringController(
+  opts: LiveMonitoringOptions,
+  cb: LiveMonitoringCallbacks,
+): {
+  start: () => void
+  stop: () => void
+  isRunning: () => boolean
+} {
+  let observer: MutationObserver | null = null
+  let timeoutId: number | null = null
+  let running = false
+  let inFlight = false
+  let previous: A11yAuditResult | null = null
+
+  let unsubscribeVisibility: (() => void) | null = null
+
+  const schedule = () => {
+    if (!running) return
+
+    if (timeoutId != null) {
+      window.clearTimeout(timeoutId)
+    }
+
+    timeoutId = window.setTimeout(async () => {
+      timeoutId = null
+
+      if (!running) return
+      if (inFlight) return
+
+      inFlight = true
+
+      try {
+        const result = await runAudit({
+          context: opts.context ?? document,
+          threshold: opts.threshold,
+          disabledRules: opts.disabledRules,
+        })
+
+        cb.onResults(result)
+
+        const filteredPrev =
+          previous == null
+            ? null
+            : {
+                ...previous,
+                issues: filterByThreshold(
+                  previous.issues,
+                  opts.threshold,
+                ).filter((issue) => !opts.disabledRules.includes(issue.ruleId)),
+              }
+
+        const filteredCurrent: A11yAuditResult = {
+          ...result,
+          issues: filterByThreshold(result.issues, opts.threshold).filter(
+            (issue) => !opts.disabledRules.includes(issue.ruleId),
+          ),
+        }
+
+        if (cb.onDiff) {
+          cb.onDiff(diffAuditResults(filteredPrev, filteredCurrent))
+        }
+
+        previous = result
+      } finally {
+        inFlight = false
+      }
+    }, opts.delay)
+  }
+
+  const start = () => {
+    if (running || typeof MutationObserver === 'undefined') return
+    running = true
+
+    const contextNode = (() => {
+      const ctx = opts.context
+      if (!ctx || ctx === document) return document.documentElement
+      if (typeof ctx === 'string') return document.querySelector(ctx)
+      if (ctx instanceof Element) return ctx
+      if (ctx instanceof Document) return ctx.documentElement
+      return document.documentElement
+    })()
+
+    const target = contextNode ?? document.documentElement
+
+    observer = new MutationObserver(() => {
+      if (document.hidden) return
+      schedule()
+    })
+
+    observer.observe(target, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+    })
+
+    const onVisibilityChange = () => {
+      if (document.hidden) {
+        if (timeoutId != null) {
+          window.clearTimeout(timeoutId)
+          timeoutId = null
+        }
+        return
+      }
+      schedule()
+    }
+
+    document.addEventListener('visibilitychange', onVisibilityChange)
+    unsubscribeVisibility = () => {
+      document.removeEventListener('visibilitychange', onVisibilityChange)
+    }
+
+    schedule()
+  }
+
+  const stop = () => {
+    running = false
+
+    if (timeoutId != null) {
+      window.clearTimeout(timeoutId)
+      timeoutId = null
+    }
+
+    if (observer) {
+      observer.disconnect()
+      observer = null
+    }
+
+    if (unsubscribeVisibility) {
+      unsubscribeVisibility()
+      unsubscribeVisibility = null
+    }
+
+    inFlight = false
+  }
+
+  return {
+    start,
+    stop,
+    isRunning: () => running,
+  }
+}

packages/devtools-a11y/src/overlay/highlight.ts

@@ -74,11 +74,9 @@ const SEVERITY_COLORS: Record<
  */
 function injectStyles(): void {
   if (document.getElementById(HIGHLIGHT_STYLE_ID)) {
-    console.log('[A11y Overlay] Styles already injected')
     return
   }
 
-  console.log('[A11y Overlay] Injecting styles into document.head')
   const style = document.createElement('style')
   style.id = HIGHLIGHT_STYLE_ID
   // Highlights use outline which doesn't affect layout
@@ -354,11 +352,6 @@ export function highlightElement(
  * Shows all issues per element in the tooltip, using the most severe for highlighting.
  */
 export function highlightAllIssues(issues: Array<A11yIssue>): void {
-  console.log(
-    '[A11y Overlay] highlightAllIssues called with',
-    issues.length,
-    'issues',
-  )
   injectStyles()
   clearHighlights()
 
@@ -383,11 +376,6 @@ export function highlightAllIssues(issues: Array<A11yIssue>): void {
   }
 
   // Highlight each selector with its most severe issue, but show all in tooltip
-  console.log(
-    '[A11y Overlay] Processing',
-    selectorIssues.size,
-    'unique selectors',
-  )
   for (const [selector, issueList] of selectorIssues) {
     // Skip empty lists (shouldn't happen, but guards against undefined)
     if (issueList.length === 0) {
@@ -401,9 +389,6 @@ export function highlightAllIssues(issues: Array<A11yIssue>): void {
 
     try {
       const elements = document.querySelectorAll(selector)
-      console.log(
-        `[A11y Overlay] Selector "${selector}" matched ${elements.length} elements`,
-      )
       if (elements.length === 0) {
         continue
       }
@@ -412,11 +397,9 @@ export function highlightAllIssues(issues: Array<A11yIssue>): void {
       elements.forEach((el) => {
         // Skip elements inside devtools
         if (isInsideDevtools(el)) {
-          console.log(`[A11y Overlay] Skipping element inside devtools:`, el)
           return
         }
 
-        console.log(`[A11y Overlay] Adding highlight class to element:`, el)
         el.classList.add(
           HIGHLIGHT_CLASS,
           `${HIGHLIGHT_CLASS}--${mostSevereImpact}`,