@reticular/speakable 1.1.1 → 1.3.0

package/dist/index.d.ts

@@ -345,4 +345,409 @@ declare function formatDiffForCI(diff: SemanticDiff): string;
  */
 declare function hasAccessibilityRegression(diff: SemanticDiff): boolean;
 
-export { type AccessibleNode, type AccessibleRole, type AccessibleState, type AccessibleValue, type AnnouncementModel, CURRENT_MODEL_VERSION, type ChangeType, type DeserializationOptions, type FocusInfo, type ModelVersion, type NodeChange, type NodePath, type PropertyChange, SUPPORTED_ROLES, type SemanticDiff, type SerializationOptions, ValidationError, cloneModel, createModel, describeChange, deserializeModel, diffAccessibilityTrees, formatDiffAsJSON, formatDiffAsText, formatDiffForCI, hasAccessibilityRegression, modelsEqual, serializeModel, validateModel, validateRole, validateState, validateTreeStructure };
+/**
+ * NVDA screen reader announcement renderer.
+ *
+ * Generates heuristic announcement text approximating NVDA output.
+ * This is NOT a perfect emulation - real NVDA behavior varies by version,
+ * settings, and context. Use for development guidance only.
+ */
+
+/**
+ * Renders an announcement model as NVDA-style announcement text.
+ *
+ * @param model - Announcement model to render
+ * @param colorize - Whether to apply ANSI color codes to the output
+ * @returns NVDA-style announcement text
+ */
+declare function renderNVDA(model: AnnouncementModel, colorize?: boolean): string;
+
+/**
+ * JAWS screen reader announcement renderer.
+ *
+ * Generates heuristic announcement text approximating JAWS output.
+ * This is NOT a perfect emulation - real JAWS behavior varies by version,
+ * settings, verbosity level, and context. Use for development guidance only.
+ */
+
+/**
+ * Renders an announcement model as JAWS-style announcement text.
+ *
+ * @param model - Announcement model to render
+ * @param colorize - Whether to apply ANSI color codes to the output
+ * @returns JAWS-style announcement text
+ */
+declare function renderJAWS(model: AnnouncementModel, colorize?: boolean): string;
+
+/**
+ * VoiceOver screen reader announcement renderer.
+ *
+ * Generates heuristic announcement text approximating VoiceOver output.
+ * This is NOT a perfect emulation - real VoiceOver behavior varies by version,
+ * settings, and context. Use for development guidance only.
+ */
+
+/**
+ * Renders an announcement model as VoiceOver-style announcement text.
+ *
+ * @param model - Announcement model to render
+ * @param colorize - Whether to apply ANSI color codes to the output
+ * @returns VoiceOver-style announcement text
+ */
+declare function renderVoiceOver(model: AnnouncementModel, colorize?: boolean): string;
+
+/**
+ * Windows Narrator screen reader announcement renderer.
+ *
+ * Generates heuristic announcement text approximating Windows Narrator output.
+ * This is NOT a perfect emulation - real Narrator behavior varies by version,
+ * settings, and context. Use for development guidance only.
+ */
+
+/**
+ * Renders an announcement model as Narrator-style announcement text.
+ *
+ * @param model - Announcement model to render
+ * @param colorize - Whether to apply ANSI color codes to the output
+ * @returns Narrator-style announcement text
+ */
+declare function renderNarrator(model: AnnouncementModel, colorize?: boolean): string;
+
+/**
+ * Developer-friendly audit report renderer.
+ *
+ * Generates human-readable accessibility audit reports with:
+ * - Landmark structure analysis
+ * - Heading hierarchy validation
+ * - Interactive element inventory
+ * - Common accessibility issue detection
+ * - Summary statistics
+ */
+
+/**
+ * Severity level for accessibility issues.
+ */
+type IssueSeverity = 'error' | 'warning' | 'info';
+/**
+ * Accessibility issue detected during audit.
+ */
+interface AccessibilityIssue {
+    severity: IssueSeverity;
+    message: string;
+    suggestion?: string;
+    element?: {
+        role: AccessibleRole;
+        name: string;
+    };
+}
+/**
+ * Audit report statistics.
+ */
+interface AuditStatistics {
+    totalElements: number;
+    roleDistribution: Record<string, number>;
+    landmarkCount: number;
+    headingCount: number;
+    interactiveCount: number;
+    focusableCount: number;
+    statesUsed: Set<string>;
+}
+/**
+ * Complete audit report.
+ */
+interface AuditReport {
+    statistics: AuditStatistics;
+    landmarks: AccessibleNode[];
+    headings: AccessibleNode[];
+    interactiveElements: AccessibleNode[];
+    issues: AccessibilityIssue[];
+}
+/**
+ * Renders an announcement model as a developer-friendly audit report.
+ *
+ * @param model - Announcement model to audit
+ * @returns Formatted audit report text
+ */
+declare function renderAuditReport(model: AnnouncementModel, colorize?: boolean): string;
+/**
+ * Generates audit report data from an announcement model.
+ *
+ * @param model - Announcement model to analyze
+ * @returns Audit report data
+ */
+declare function generateAuditReport(model: AnnouncementModel): AuditReport;
+
+/**
+ * HTML parsing using jsdom.
+ *
+ * Provides lenient parsing with error recovery for malformed HTML.
+ */
+/**
+ * Parsing error class.
+ */
+declare class ParsingError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Parsing warning.
+ */
+interface ParsingWarning {
+    message: string;
+    line?: number;
+    column?: number;
+}
+/**
+ * Result of HTML parsing.
+ */
+interface ParseResult {
+    /** Parsed DOM document */
+    document: Document;
+    /** Warnings encountered during parsing */
+    warnings: ParsingWarning[];
+}
+/**
+ * Parses HTML string into a DOM document.
+ *
+ * Uses jsdom with lenient parsing mode to handle malformed HTML.
+ * Emits warnings for issues but continues processing.
+ *
+ * @param html - HTML string to parse
+ * @returns Parse result with document and warnings
+ * @throws ParsingError if parsing fails completely or input exceeds size limit
+ */
+declare function parseHTML(html: string): ParseResult;
+/**
+ * Parses HTML and returns just the document (throws on warnings).
+ *
+ * Convenience function for cases where warnings should be treated as errors.
+ *
+ * @param html - HTML string to parse
+ * @returns Parsed DOM document
+ * @throws ParsingError if parsing fails or warnings are present
+ */
+declare function parseHTMLStrict(html: string): Document;
+/**
+ * Validates that HTML string is not empty.
+ *
+ * @param html - HTML string to validate
+ * @throws ParsingError if HTML is empty or whitespace-only
+ */
+declare function validateHTMLNotEmpty(html: string): void;
+
+/**
+ * ARIA accessible name computation.
+ *
+ * Implements the ARIA name computation algorithm following the W3C specification.
+ * https://www.w3.org/TR/accname-1.2/
+ */
+/**
+ * Warning emitted during name computation.
+ */
+interface NameComputationWarning {
+    message: string;
+    element: Element;
+}
+/**
+ * Result of name computation.
+ */
+interface NameComputationResult {
+    name: string;
+    warnings: NameComputationWarning[];
+}
+/**
+ * Result of description computation.
+ */
+interface DescriptionComputationResult {
+    description: string;
+    warnings: NameComputationWarning[];
+}
+/**
+ * Computes the accessible name for an element following ARIA specification.
+ *
+ * Priority order:
+ * 1. aria-labelledby (references to other elements)
+ * 2. aria-label
+ * 3. Native label (for form controls)
+ * 4. alt attribute (for images)
+ * 5. Text content (for elements that support it)
+ * 6. title attribute (fallback)
+ *
+ * @param element - Element to compute name for
+ * @param visited - Set of visited elements (for cycle detection)
+ * @returns Computed accessible name and warnings
+ */
+declare function computeAccessibleName(element: Element, visited?: Set<Element>): NameComputationResult;
+/**
+ * Computes the accessible description for an element.
+ *
+ * Priority order:
+ * 1. aria-describedby (references to other elements)
+ * 2. title attribute (fallback)
+ *
+ * @param element - Element to compute description for
+ * @returns Computed accessible description and warnings
+ */
+declare function computeAccessibleDescription(element: Element): DescriptionComputationResult;
+
+/**
+ * Role computation and mapping.
+ *
+ * Maps HTML elements to their implicit ARIA roles and validates explicit roles.
+ */
+
+/**
+ * Warning emitted during role computation.
+ */
+interface RoleComputationWarning {
+    message: string;
+    element: Element;
+}
+/**
+ * Result of role computation.
+ */
+interface RoleComputationResult {
+    role: AccessibleRole | null;
+    warnings: RoleComputationWarning[];
+}
+/**
+ * Computes the accessible role for an element.
+ *
+ * Priority:
+ * 1. Explicit role attribute (if valid)
+ * 2. Implicit role based on element type
+ * 3. null if no role
+ *
+ * @param element - Element to compute role for
+ * @returns Computed role and warnings
+ */
+declare function computeRole(element: Element): RoleComputationResult;
+/**
+ * Checks if an element should be included in the accessibility tree.
+ *
+ * Elements are excluded if:
+ * - They have role="presentation" or role="none"
+ * - They have aria-hidden="true"
+ * - They have no accessible role
+ *
+ * @param element - Element to check
+ * @returns true if element should be included
+ */
+declare function isAccessible(element: Element): boolean;
+
+/**
+ * State and property extraction from ARIA attributes.
+ *
+ * Extracts accessibility states and properties from elements.
+ */
+
+/**
+ * Warning emitted during state extraction.
+ */
+interface StateExtractionWarning {
+    message: string;
+    element: Element;
+}
+/**
+ * Result of state extraction.
+ */
+interface StateExtractionResult {
+    state: AccessibleState;
+    warnings: StateExtractionWarning[];
+}
+/**
+ * Result of value extraction.
+ */
+interface ValueExtractionResult {
+    value: AccessibleValue | undefined;
+    warnings: StateExtractionWarning[];
+}
+/**
+ * Extracts accessibility state from an element.
+ *
+ * Extracts ARIA state attributes and native element states.
+ *
+ * @param element - Element to extract state from
+ * @returns Extracted state and warnings
+ */
+declare function extractState(element: Element): StateExtractionResult;
+/**
+ * Extracts value information from form controls.
+ *
+ * @param element - Element to extract value from
+ * @returns Extracted value and warnings
+ */
+declare function extractValue(element: Element): ValueExtractionResult;
+
+/**
+ * Focus information extraction.
+ *
+ * Determines focusability and tabindex for elements.
+ */
+
+/**
+ * Extracts focus information from an element.
+ *
+ * Determines if an element is focusable and extracts explicit tabindex.
+ *
+ * @param element - Element to extract focus info from
+ * @returns Focus information
+ */
+declare function extractFocusInfo(element: Element): FocusInfo;
+
+/**
+ * Accessibility tree builder.
+ *
+ * Builds the complete accessibility tree from a DOM tree by integrating
+ * all extraction components (role, name, description, state, value, focus).
+ *
+ * Supports transparent traversal through role-less elements, text node
+ * capture as staticText nodes, shadow DOM traversal, and CSS hidden state.
+ */
+
+/**
+ * Warning emitted during tree building.
+ */
+interface TreeBuildWarning {
+    message: string;
+    element: Element;
+}
+/**
+ * Result of tree building.
+ */
+interface TreeBuildResult {
+    model: AnnouncementModel;
+    warnings: TreeBuildWarning[];
+}
+/**
+ * Error thrown when selector filtering fails.
+ */
+declare class SelectorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Builds an accessibility tree from a DOM element.
+ *
+ * Traverses the DOM tree depth-first, applies all extractors,
+ * filters inaccessible elements, and builds the hierarchical tree.
+ *
+ * @param rootElement - Root DOM element to build tree from
+ * @param sourceHash - Optional hash of source HTML for change detection
+ * @returns Announcement model and warnings
+ */
+declare function buildAccessibilityTree(rootElement: Element, sourceHash?: string): TreeBuildResult;
+/**
+ * Builds accessibility trees for elements matching a CSS selector.
+ *
+ * Uses querySelector/querySelectorAll to find matching elements,
+ * then builds an accessibility tree for each match.
+ *
+ * @param rootElement - Root DOM element to search within
+ * @param selector - CSS selector to match elements
+ * @param sourceHash - Optional hash of source HTML for change detection
+ * @returns Array of announcement models and warnings
+ * @throws SelectorError if no elements match the selector
+ */
+declare function buildAccessibilityTreeWithSelector(rootElement: Element, selector: string, sourceHash?: string): TreeBuildResult[];
+
+export { type AccessibilityIssue, type AccessibleNode, type AccessibleRole, type AccessibleState, type AccessibleValue, type AnnouncementModel, type AuditReport, type AuditStatistics, CURRENT_MODEL_VERSION, type ChangeType, type DescriptionComputationResult, type DeserializationOptions, type FocusInfo, type IssueSeverity, type ModelVersion, type NameComputationResult, type NameComputationWarning, type NodeChange, type NodePath, type ParseResult, ParsingError, type ParsingWarning, type PropertyChange, type RoleComputationResult, type RoleComputationWarning, SUPPORTED_ROLES, SelectorError, type SemanticDiff, type SerializationOptions, type StateExtractionResult, type StateExtractionWarning, type TreeBuildResult, type TreeBuildWarning, ValidationError, type ValueExtractionResult, buildAccessibilityTree, buildAccessibilityTreeWithSelector, cloneModel, computeAccessibleDescription, computeAccessibleName, computeRole, createModel, describeChange, deserializeModel, diffAccessibilityTrees, extractFocusInfo, extractState, extractValue, formatDiffAsJSON, formatDiffAsText, formatDiffForCI, generateAuditReport, hasAccessibilityRegression, isAccessible, modelsEqual, parseHTML, parseHTMLStrict, renderAuditReport, renderJAWS, renderNVDA, renderNarrator, renderVoiceOver, serializeModel, validateHTMLNotEmpty, validateModel, validateRole, validateState, validateTreeStructure };