@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/a11y.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Accessibility (A11y) Module
+ *
+ * Provides directives and utilities for accessibility compliance:
+ * - `@a11y('type', 'message')` - Add accessibility hints as HTML comments
+ * - `@screenReader(...)@endScreenReader` - Screen reader only content
+ * - `@ariaDescribe('id', 'description')` - Connect elements with descriptions
+ *
+ * Also provides automated accessibility checking via `checkA11y()` and
+ * directory scanning via `scanA11yIssues()`.
+ *
+ * ## Accessibility Checks
+ *
+ * The automated checker validates:
+ * - Images have alt attributes
+ * - Interactive elements have accessible names
+ * - Form inputs have associated labels
+ * - Heading hierarchy is maintained
+ * - Document has lang attribute
+ * - A right-to-left lang is paired with dir="rtl"
+ */
+import type { CustomDirective, StxOptions } from './types';
+export interface A11yViolation {
+    /** Type/category of violation */
+    type: string;
+    /** The problematic HTML element */
+    element: string;
+    /** Description of the issue */
+    message: string;
+    /** Impact level of the violation */
+    impact: 'critical' | 'serious' | 'moderate' | 'minor';
+    /** Suggested fix */
+    help: string;
+    /** URL to more information */
+    helpUrl?: string;
+}
+/**
+ * Has this element declared itself decorative rather than semantic?
+ *
+ * `role="presentation"` and its synonym `role="none"` remove an element's
+ * implicit semantics from the accessibility tree. On a table that is exactly the
+ * declaration that it carries layout, not data — so demanding a `<th>` or a
+ * `<caption>` asks the author to reintroduce the semantics the role exists to
+ * remove (stacksjs/stx#1916).
+ *
+ * This is not a corner case. Every HTML email is nested layout tables: mail
+ * clients strip `<style>` and have no reliable box model, so `role="presentation"`
+ * is the standard, correct pattern there. One email template accounted for every
+ * remaining finding in an otherwise-clean app, and none of them was fixable —
+ * the correct markup was what triggered them. An advisory checker with a
+ * permanent finding nobody can close is one people learn to ignore, which costs
+ * more than the rule is worth.
+ *
+ * The rule itself is right to exist: a DATA table with no headers is a real
+ * problem. It just has to take the author's word for which kind it is.
+ */
+export declare function isPresentationalRole(role: string | null | undefined): boolean;
+/** Read one attribute out of a raw tag's attribute text. */
+export declare function attributeValue(attrs: string, name: string): string | null;
+/**
+ * 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;
+/**
+ * Regex-based accessibility checker for non-DOM environments.
+ * Provides a subset of checks that can be performed with regex parsing.
+ *
+ * @param html - HTML content to check
+ * @param _filePath - File path for error reporting
+ * @returns Array of accessibility violations found
+ */
+/**
+ * Regex-based checking, used when no DOM is available — which is the CLI.
+ *
+ * Exported so tests can exercise it directly. It and the DOM path implement the
+ * same rules twice, and the way two implementations of one rule go wrong is by
+ * disagreeing; pinning only whichever one the test environment happens to pick
+ * leaves the other free to drift (#1916).
+ */
+export declare function checkA11yWithRegex(html: string, _filePath: string): A11yViolation[];
+/**
+ * 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[]>;
+/** What a scan actually read, alongside what it found. */
+export interface A11yScanResult {
+    /** Files that had at least one violation, mapped to their violations. */
+    results: Record<string, A11yViolation[]>;
+    /**
+     * Every file the scan READ.
+     *
+     * Reported separately because "no violations" and "no files" are different
+     * answers that used to be the same one: `results` only ever contains files
+     * WITH violations, so an empty map means both "everything is clean" and
+     * "nothing was scanned", and the success banner was printed for both
+     * (stacksjs/stx#1918).
+     */
+    scannedFiles: string[];
+}
+/**
+ * Scan a directory, a file, or a glob for accessibility issues.
+ *
+ * The argument used to be joined into a scan pattern, so only a directory
+ * worked: a file path became `<file>/**` + `/*.stx` and a glob became a doubled
+ * pattern, both matching nothing and both reported as a clean pass. See
+ * `resolve-stx-targets.ts` for what that cost.
+ */
+export declare function scanA11yTargets(target: string | readonly string[], options?: {
+    recursive?: boolean;
+    ignorePaths?: string[];
+}): Promise<A11yScanResult>;
+/**
+ * Back-compatible wrapper: violations only.
+ *
+ * Kept so existing callers keep working, but it cannot say whether the scan read
+ * anything — which is the distinction #1918 turned on. Prefer
+ * {@link scanA11yTargets}.
+ */
+export declare function scanA11yIssues(directory: string, options?: {
+    recursive?: boolean;
+    ignorePaths?: string[];
+}): Promise<Record<string, A11yViolation[]>>;
+/**
+ * Auto-fix result
+ */
+export interface A11yFixResult {
+    /** Original HTML */
+    original: string;
+    /** Fixed HTML */
+    fixed: string;
+    /** Number of fixes applied */
+    fixCount: number;
+    /** Details of each fix */
+    fixes: Array<{
+        type: string;
+        description: string;
+        before: string;
+        after: string;
+    }>;
+}
+/**
+ * Auto-fix configuration
+ */
+export interface A11yAutoFixConfig {
+    /** Fix images without alt text by adding empty alt="" */
+    fixMissingAlt?: boolean;
+    /** Fix buttons/links without accessible names by adding aria-label */
+    fixMissingLabels?: boolean;
+    /** Fix form inputs without labels by adding aria-label */
+    fixMissingFormLabels?: boolean;
+    /** Fix tables without headers by adding scope attribute */
+    fixTableHeaders?: boolean;
+    /** Add lang attribute to html element */
+    fixMissingLang?: boolean;
+    /** Add dir="rtl" when the html element's lang is a right-to-left language */
+    fixMissingDir?: boolean;
+    /** Fix positive tabindex values */
+    fixPositiveTabindex?: boolean;
+    /** Fix custom buttons without tabindex */
+    fixButtonFocusable?: boolean;
+    /** Default language for lang attribute */
+    defaultLang?: string;
+}
+/**
+ * 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?: boolean): 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>>;
+/**
+ * A11y directive for adding accessibility hints
+ */
+export declare const a11yDirective: CustomDirective;
+/**
+ * Screen reader directive for screen reader only content
+ */
+export declare const screenReaderDirective: CustomDirective;
+/**
+ * Register all a11y directives
+ */
+export declare function registerA11yDirectives(): CustomDirective[];