@needle-tools/engine/lib/engine/engine_accessibility.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { Object3D } from "three";
import type { Context } from "./engine_setup";
import { IComponent } from "./engine_types.js";
/** Data describing the accessible semantics for a 3D object or component. */
type AccessibilityData = {
    /** ARIA role (e.g. `"button"`, `"img"`, `"region"`). */
    role: string;
    /** Human-readable label announced by screen readers. */
    label: string;
    /** When `true`, the element is hidden from the accessibility tree. */
    hidden?: boolean;
    /** When `true`, indicates the element's content is being updated. */
    busy?: boolean;
};
/**
 * Manages an accessible, screen-reader-friendly overlay for a Needle Engine {@link Context}.
 *
 * The manager maintains a visually-hidden DOM tree that mirrors relevant 3D scene objects
 * with appropriate ARIA roles and labels. It also provides a live region so that hover
 * events in the 3D scene can be announced to assistive technology without stealing focus.
 *
 * ## Automatic integration
 * Several built-in components register accessible elements automatically:
 * - {@link DragControls} — announces draggable objects and drag state
 * - {@link Button} — exposes UI buttons to the accessibility tree
 * - {@link Text} — exposes UI text content to screen readers
 * - {@link ChangeTransformOnClick} — announces clickable transform actions
 * - {@link ChangeMaterialOnClick} — announces clickable material changes
 * - {@link EmphasizeOnClick} — announces clickable emphasis effects
 * - {@link PlayAudioOnClick} — announces clickable audio playback
 * - {@link PlayAnimationOnClick} — announces clickable animation triggers
 *
 * ## What this unlocks
 * - Hovering over buttons and interactive objects with the cursor announces them to screen readers via an ARIA live region — no focus steal required
 * - Screen readers can discover and navigate interactive 3D objects in the scene
 * - Drag operations update the accessibility state (busy, label changes) in real time
 * - Custom components can participate by calling {@link updateElement}, {@link focus}, and {@link hover}
 *
 * Access the manager via `this.context.accessibility` from any component.
 */
export declare class AccessibilityManager {
    private readonly context;
    private static readonly _managers;
    /** Returns the {@link AccessibilityManager} associated with the given context or component. */
    static get(obj: Context | IComponent): AccessibilityManager | undefined;
    constructor(context: Context);
    private _enabled;
    /** Enables or disables the accessibility overlay. When disabled, the overlay DOM is removed. */
    set enabled(value: boolean);
    /** Removes all tracked accessibility elements, keeping only the live region. */
    clear(): void;
    /** Removes the overlay from the DOM and unregisters this manager from the context. */
    dispose(): void;
    private readonly root;
    private readonly liveRegion;
    private readonly treeElements;
    /**
     * Creates or updates the accessible DOM element for a 3D object or component.
     * @param obj - The scene object or component to represent.
     * @param data - Partial accessibility data (role, label, hidden, busy) to apply.
     */
    updateElement<T extends Object3D | IComponent>(obj: T, data: Partial<AccessibilityData>): void;
    /** Moves keyboard focus to the accessible element representing the given object. */
    focus<T extends Object3D | IComponent>(obj: T): void;
    /** Removes keyboard focus from the accessible element representing the given object. */
    unfocus<T extends Object3D | IComponent>(obj: T): void;
    /**
     * Announces a hover event to screen readers via the ARIA live region.
     * @param obj - The hovered object (used to look up its label if `text` is not provided).
     * @param text - Optional text to announce. Falls back to the element's `aria-label`.
     */
    hover<T extends Object3D | IComponent>(obj: T, text?: string): void;
    /** Removes the accessible DOM element for the given object and stops tracking it. */
    removeElement(obj: Object3D | IComponent): void;
    private set liveRegionMode(value);
}
export {};