@stacksjs/stx/dist/a11y.d.ts

A performant UI Framework. Powered by Bun.

import type { CustomDirective, StxOptions } from './types';
/**
 * Process accessibility directives.
 * Handles @a11y hints, @screenReader content, and @ariaDescribe.
 */
export declare function processA11yDirectives(template: string, _context: Record<string, any>, _filePath: string, _options: StxOptions): string;
/**
 * Create the screen reader only CSS style.
 * Add this to your stylesheet or inject via `<style>` tag.
 */
export declare function getScreenReaderOnlyStyle(): string;
/**
 * Check if DOM environment is available.
 * Useful for determining which accessibility checking mode will be used.
 *
 * @returns true if DOM APIs are available (happy-dom, jsdom, browser)
 *
 * @example
 * ```typescript
 * if (hasDOMSupport()) {
 *   console.log('Using full DOM-based a11y checking')
 * } else {
 *   console.log('Using regex-based a11y checking (limited)')
 * }
 * ```
 */
export declare function hasDOMSupport(): boolean;
/**
 * Automatically check template for accessibility issues.
 *
 * This function works in both DOM and non-DOM environments:
 * - With DOM (happy-dom/jsdom): Full accessibility checking with element traversal
 * - Without DOM: Regex-based checking for common issues
 *
 * @param html - HTML content to check
 * @param filePath - File path for error reporting
 * @returns Array of accessibility violations found
 *
 * @example
 * ```typescript
 * const violations = await checkA11y('<img src="photo.jpg">', 'page.html')
 * // violations[0].type === 'missing-alt'
 * ```
 */
export declare function checkA11y(html: string, filePath: string): Promise<A11yViolation[]>;
/**
 * Scan a directory of stx files for accessibility issues.
 * Returns a map of file paths to their violations.
 */
export declare function scanA11yIssues(directory: string, options?: { recursive?: boolean, ignorePaths?: string[] }): Promise<Record<string, A11yViolation[]>>;
/**
 * Auto-fix accessibility issues in HTML content.
 *
 * This function attempts to automatically fix common accessibility issues.
 * Note that some fixes may require manual review to ensure they make sense
 * in context (e.g., alt text should be descriptive, not just present).
 *
 * @param html - HTML content to fix
 * @param config - Auto-fix configuration
 * @returns Fixed HTML and details of changes made
 *
 * @example
 * const result = autoFixA11y('<img src="photo.jpg">')
 * // result.fixed = '<img src="photo.jpg" alt="">'
 * // result.fixCount = 1
 */
export declare function autoFixA11y(html: string, config?: A11yAutoFixConfig): A11yFixResult;
/**
 * Auto-fix accessibility issues in a file and optionally write back.
 *
 * @param filePath - Path to the file to fix
 * @param config - Auto-fix configuration
 * @param writeBack - Whether to write the fixed content back to the file
 * @returns Fix result
 */
export declare function autoFixA11yFile(filePath: string, config?: A11yAutoFixConfig, writeBack?: any): Promise<A11yFixResult>;
/**
 * Auto-fix accessibility issues in a directory of files.
 *
 * @param directory - Directory to scan
 * @param config - Auto-fix configuration
 * @param options - Scan options
 * @param options.recursive - Whether to scan recursively (default: true)
 * @param options.ignorePaths - Paths to ignore
 * @param options.writeBack - Whether to write fixes back to files (default: false)
 * @param options.extensions - File extensions to process (default: ['.stx', '.html', '.htm'])
 * @returns Map of file paths to fix results
 */
export declare function autoFixA11yDirectory(directory: string, config?: A11yAutoFixConfig, options?: {
    recursive?: boolean
    ignorePaths?: string[]
    writeBack?: boolean
    extensions?: string[]
  }): Promise<Record<string, A11yFixResult>>;
/**
 * Register all a11y directives
 */
export declare function registerA11yDirectives(): CustomDirective[];
/**
 * A11y directive for adding accessibility hints
 */
export declare const a11yDirective: CustomDirective;
/**
 * Screen reader directive for screen reader only content
 */
export declare const screenReaderDirective: CustomDirective;
/**
 * Accessibility violation found during a11y checks
 */
export declare interface A11yViolation {
  type: string
  element: string
  message: string
  impact: 'critical' | 'serious' | 'moderate' | 'minor'
  help: string
  helpUrl?: string
}
/**
 * Auto-fix result
 */
export declare interface A11yFixResult {
  original: string
  fixed: string
  fixCount: number
  fixes: Array<{
    type: string
    description: string
    before: string
    after: string
  }>
}
/**
 * Auto-fix configuration
 */
export declare interface A11yAutoFixConfig {
  fixMissingAlt?: boolean
  fixMissingLabels?: boolean
  fixMissingFormLabels?: boolean
  fixTableHeaders?: boolean
  fixMissingLang?: boolean
  fixPositiveTabindex?: boolean
  fixButtonFocusable?: boolean
  defaultLang?: string
}