@reticular/speakable 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+/**
+ * Canonical Announcement Model - Version 1
+ *
+ * Platform-agnostic representation of accessibility semantics.
+ * Deterministic, serializable, suitable for snapshot testing.
+ */
+/**
+ * Model version for forward compatibility.
+ * Breaking changes increment major version.
+ */
+interface ModelVersion {
+    major: number;
+    minor: number;
+}
+/**
+ * Accessible role following ARIA specification.
+ * V1 supports common interactive and structural roles.
+ */
+type AccessibleRole = 'button' | 'link' | 'heading' | 'textbox' | 'checkbox' | 'radio' | 'combobox' | 'listbox' | 'option' | 'list' | 'listitem' | 'article' | 'generic' | 'navigation' | 'main' | 'banner' | 'contentinfo' | 'region' | 'img' | 'complementary' | 'form' | 'search' | 'paragraph' | 'blockquote' | 'code' | 'staticText' | 'table' | 'row' | 'cell' | 'columnheader' | 'rowheader' | 'term' | 'definition' | 'figure' | 'caption' | 'group' | 'dialog' | 'meter' | 'progressbar' | 'status' | 'document' | 'application' | 'separator';
+/**
+ * Accessible states and properties.
+ * Only includes properties relevant to the element's role.
+ */
+interface AccessibleState {
+    /** Whether the element is expanded (e.g., accordion, dropdown) */
+    expanded?: boolean;
+    /** Whether the element is checked (checkbox, radio, or mixed state) */
+    checked?: boolean | 'mixed';
+    /** Whether the element is pressed (toggle button) */
+    pressed?: boolean | 'mixed';
+    /** Whether the element is selected (option, tab, etc.) */
+    selected?: boolean;
+    /** Whether the element is disabled */
+    disabled?: boolean;
+    /** Whether the element has invalid input */
+    invalid?: boolean;
+    /** Whether the element is required */
+    required?: boolean;
+    /** Whether the element is read-only */
+    readonly?: boolean;
+    /** Whether the element is busy loading */
+    busy?: boolean;
+    /** Current page/step/location indicator */
+    current?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | false;
+    /** Whether the element is grabbed for drag-and-drop */
+    grabbed?: boolean;
+    /** Whether the element is hidden from accessibility tree */
+    hidden?: boolean;
+    /** Heading level (1-6) */
+    level?: number;
+    /** Position in set (1-indexed) for lists, tabs, etc. */
+    posinset?: number;
+    /** Total size of set */
+    setsize?: number;
+}
+/**
+ * Value for form controls and range widgets.
+ */
+interface AccessibleValue {
+    /** Current value */
+    current: string | number;
+    /** Minimum value (for range widgets) */
+    min?: number;
+    /** Maximum value (for range widgets) */
+    max?: number;
+    /** Textual representation (e.g., "50%") */
+    text?: string;
+}
+/**
+ * Focusability information.
+ */
+interface FocusInfo {
+    /** Whether the element can receive focus */
+    focusable: boolean;
+    /** Explicit tabindex value (only present if explicitly set) */
+    tabindex?: number;
+}
+/**
+ * Single node in the accessibility tree.
+ */
+interface AccessibleNode {
+    /** ARIA role of the element */
+    role: AccessibleRole;
+    /** Accessible name (computed via ARIA name algorithm) */
+    name: string;
+    /** Accessible description (aria-describedby, title, etc.) */
+    description?: string;
+    /** Value for form controls */
+    value?: AccessibleValue;
+    /** State properties */
+    state: AccessibleState;
+    /** Focus information */
+    focus: FocusInfo;
+    /** Child nodes in the accessibility tree */
+    children: AccessibleNode[];
+}
+/**
+ * Root of the Canonical Announcement Model.
+ */
+interface AnnouncementModel {
+    /** Model version for forward compatibility */
+    version: ModelVersion;
+    /** Root node of the accessibility tree */
+    root: AccessibleNode;
+    /** Metadata about the extraction */
+    metadata: {
+        /** ISO 8601 timestamp of extraction */
+        extractedAt: string;
+        /** Optional hash of source HTML for change detection */
+        sourceHash?: string;
+    };
+}
+/**
+ * Supported roles as a constant array for validation.
+ */
+declare const SUPPORTED_ROLES: readonly AccessibleRole[];
+/**
+ * Current model version constant.
+ */
+declare const CURRENT_MODEL_VERSION: ModelVersion;
+
+/**
+ * Validation functions for the Canonical Announcement Model.
+ */
+
+/**
+ * Validation error class.
+ */
+declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates that a role is supported in V1.
+ *
+ * @param role - The role to validate
+ * @returns true if valid
+ * @throws ValidationError if invalid
+ */
+declare function validateRole(role: string): role is AccessibleRole;
+/**
+ * Validates accessible state constraints.
+ *
+ * @param state - The state object to validate
+ * @throws ValidationError if invalid
+ */
+declare function validateState(state: AccessibleState): void;
+/**
+ * Validates tree structure integrity (no cycles).
+ *
+ * @param node - The root node to validate
+ * @param visited - Set of visited nodes (for cycle detection)
+ * @throws ValidationError if cycles detected
+ */
+declare function validateTreeStructure(node: AccessibleNode, visited?: Set<AccessibleNode>): void;
+/**
+ * Validates an entire AnnouncementModel.
+ *
+ * @param model - The model to validate
+ * @throws ValidationError if invalid
+ */
+declare function validateModel(model: AnnouncementModel): void;
+
+/**
+ * JSON serialization and deserialization for the Canonical Announcement Model.
+ *
+ * Ensures deterministic output with consistent property ordering.
+ */
+
+/**
+ * Serialization options.
+ */
+interface SerializationOptions {
+    /** Whether to pretty-print the JSON output */
+    pretty?: boolean;
+    /** Whether to validate the model before serialization */
+    validate?: boolean;
+}
+/**
+ * Deserialization options.
+ */
+interface DeserializationOptions {
+    /** Whether to validate the model after deserialization */
+    validate?: boolean;
+}
+/**
+ * Serializes an AnnouncementModel to JSON string.
+ *
+ * Produces deterministic output with consistent property ordering.
+ *
+ * @param model - The model to serialize
+ * @param options - Serialization options
+ * @returns JSON string representation
+ * @throws ValidationError if validation is enabled and model is invalid
+ */
+declare function serializeModel(model: AnnouncementModel, options?: SerializationOptions): string;
+/**
+ * Deserializes a JSON string to an AnnouncementModel.
+ *
+ * @param json - JSON string to deserialize
+ * @param options - Deserialization options
+ * @returns Parsed AnnouncementModel
+ * @throws SyntaxError if JSON is invalid
+ * @throws ValidationError if validation is enabled and model is invalid
+ */
+declare function deserializeModel(json: string, options?: DeserializationOptions): AnnouncementModel;
+/**
+ * Creates a new AnnouncementModel with current version and timestamp.
+ *
+ * @param root - Root accessible node
+ * @param sourceHash - Optional hash of source HTML
+ * @returns New AnnouncementModel
+ */
+declare function createModel(root: AccessibleNode, sourceHash?: string): AnnouncementModel;
+/**
+ * Compares two models for equality (deep comparison).
+ *
+ * @param a - First model
+ * @param b - Second model
+ * @returns true if models are equivalent
+ */
+declare function modelsEqual(a: AnnouncementModel, b: AnnouncementModel): boolean;
+/**
+ * Clones a model (deep copy).
+ *
+ * @param model - Model to clone
+ * @returns Deep copy of the model
+ */
+declare function cloneModel(model: AnnouncementModel): AnnouncementModel;
+
+/**
+ * Semantic diff types for comparing accessibility trees.
+ */
+
+/**
+ * Type of change detected in the diff.
+ */
+type ChangeType = 'added' | 'removed' | 'changed';
+/**
+ * JSON path to a node in the tree (e.g., "root.children[0].children[1]").
+ */
+type NodePath = string;
+/**
+ * Details about what changed in a node.
+ */
+interface PropertyChange {
+    /** Property that changed */
+    property: 'role' | 'name' | 'description' | 'value' | 'state' | 'focus';
+    /** Old value (undefined for added nodes) */
+    oldValue?: unknown;
+    /** New value (undefined for removed nodes) */
+    newValue?: unknown;
+}
+/**
+ * A single change in the accessibility tree.
+ */
+interface NodeChange {
+    /** Type of change */
+    type: ChangeType;
+    /** JSON path to the node */
+    path: NodePath;
+    /** The node itself (for added/removed) or property changes (for changed) */
+    node?: AccessibleNode;
+    /** Specific property changes (only for type='changed') */
+    changes?: PropertyChange[];
+}
+/**
+ * Complete diff between two accessibility trees.
+ */
+interface SemanticDiff {
+    /** All detected changes */
+    changes: NodeChange[];
+    /** Summary statistics */
+    summary: {
+        added: number;
+        removed: number;
+        changed: number;
+        total: number;
+    };
+}
+
+/**
+ * Semantic diff algorithm for accessibility trees.
+ *
+ * Compares two accessibility trees and identifies:
+ * - Added nodes (present in new tree, not in old)
+ * - Removed nodes (present in old tree, not in new)
+ * - Changed nodes (same path, different properties)
+ */
+
+/**
+ * Compare two accessibility trees and generate a semantic diff.
+ *
+ * @param oldTree - The original accessibility tree
+ * @param newTree - The updated accessibility tree
+ * @returns Semantic diff with all detected changes
+ */
+declare function diffAccessibilityTrees(oldTree: AccessibleNode, newTree: AccessibleNode): SemanticDiff;
+/**
+ * Generate a human-readable description of a change.
+ *
+ * @param change - The change to describe
+ * @returns Human-readable description
+ */
+declare function describeChange(change: NodeChange): string;
+
+/**
+ * Formatting utilities for semantic diff output.
+ *
+ * Provides JSON and human-readable text formatting for diffs.
+ */
+
+/**
+ * Format a semantic diff as pretty-printed JSON.
+ *
+ * @param diff - The semantic diff to format
+ * @returns JSON string with 2-space indentation
+ */
+declare function formatDiffAsJSON(diff: SemanticDiff): string;
+/**
+ * Format a semantic diff as human-readable text.
+ *
+ * @param diff - The semantic diff to format
+ * @returns Multi-line text description of changes
+ */
+declare function formatDiffAsText(diff: SemanticDiff): string;
+/**
+ * Format a semantic diff for CI/CD tools (GitHub Actions, GitLab CI, etc.).
+ *
+ * Uses a format that's easy to parse and diff-friendly.
+ *
+ * @param diff - The semantic diff to format
+ * @returns CI-friendly text output
+ */
+declare function formatDiffForCI(diff: SemanticDiff): string;
+/**
+ * Check if a diff represents a regression (accessibility got worse).
+ *
+ * Heuristics:
+ * - Removed nodes with important roles (button, link, heading, etc.)
+ * - Changed nodes that lost accessible names
+ * - Changed nodes that became disabled or hidden
+ *
+ * @param diff - The semantic diff to analyze
+ * @returns True if potential regression detected
+ */
+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 };