Source: accessibility/AccessibilitySystem.ts

import { FederatedEvent } from '../events/FederatedEvent';
import { ExtensionType } from '../extensions/Extensions';
import { isMobile } from '../utils/browser/isMobile';
import { removeItems } from '../utils/data/removeItems';
import { type AccessibleHTMLElement } from './accessibilityTarget';

import type { Rectangle } from '../maths/shapes/Rectangle';
import type { System } from '../rendering/renderers/shared/system/System';
import type { Renderer } from '../rendering/renderers/types';
import type { Container } from '../scene/container/Container';
import type { isMobileResult } from '../utils/browser/isMobile';

/**
 * The accessibility module recreates the ability to tab and have content read by screen readers.
 * This is very important as it can possibly help people with disabilities access PixiJS content.
 *
 * This module is a mixin for AbstractRenderer and will need to be imported if you are managing your own renderer.
 * Usage:
 * ```js
 * import 'pixi.js/accessibility';
 * ```
 * To make an object accessible do the following:
 * ```js
 * container.accessible = true; // object is now accessible to screen readers!
 * ```
 * See AccessibleOptions for more accessibility related properties that can be set.
 * @namespace accessibility
 */

/** @ignore */
const KEY_CODE_TAB = 9;

const DIV_TOUCH_SIZE = 100;
const DIV_TOUCH_POS_X = 0;
const DIV_TOUCH_POS_Y = 0;
const DIV_TOUCH_ZINDEX = 2;

const DIV_HOOK_SIZE = 1;
const DIV_HOOK_POS_X = -1000;
const DIV_HOOK_POS_Y = -1000;
const DIV_HOOK_ZINDEX = 2;

/** @ignore */
export interface AccessibilityOptions
{
    /** Setting this to true will visually show the divs. */
    debug?: boolean;
}

/**
 * The Accessibility system recreates the ability to tab and have content read by screen readers.
 * This is very important as it can possibly help people with disabilities access PixiJS content.
 *
 * A Container can be made accessible just like it can be made interactive. This manager will map the
 * events as if the mouse was being used, minimizing the effort required to implement.
 *
 * An instance of this class is automatically created by default, and can be found at `renderer.accessibility`
 * @memberof accessibility
 */
export class AccessibilitySystem implements System<AccessibilityOptions>
{
    /** @ignore */
    public static extension = {
        type: [
            ExtensionType.WebGLSystem,
            ExtensionType.WebGPUSystem,
        ],
        name: 'accessibility',
    } as const;

    /** Setting this to true will visually show the divs. */
    public debug = false;

    /**
     * The renderer this accessibility manager works for.
     * @type {WebGLRenderer|WebGPURenderer}
     */
    private _renderer: Renderer;

    /** Internal variable, see isActive getter. */
    private _isActive = false;

    /** Internal variable, see isMobileAccessibility getter. */
    private _isMobileAccessibility = false;

    /** Button element for handling touch hooks. */
    private _hookDiv: HTMLElement | null;

    /** This is the dom element that will sit over the PixiJS element. This is where the div overlays will go. */
    private _div: HTMLElement;

    /** A simple pool for storing divs. */
    private _pool: AccessibleHTMLElement[] = [];

    /** This is a tick used to check if an object is no longer being rendered. */
    private _renderId = 0;

    /** The array of currently active accessible items. */
    private _children: Container[] = [];

    /** Count to throttle div updates on android devices. */
    private _androidUpdateCount = 0;

    /**  The frequency to update the div elements. */
    private readonly _androidUpdateFrequency = 500; // 2fps

    // eslint-disable-next-line jsdoc/require-param
    /**
     * @param {WebGLRenderer|WebGPURenderer} renderer - A reference to the current renderer
     */
    constructor(renderer: Renderer, private readonly _mobileInfo: isMobileResult = isMobile)
    {
        this._hookDiv = null;

        if (_mobileInfo.tablet || _mobileInfo.phone)
        {
            this._createTouchHook();
        }

        // first we create a div that will sit over the PixiJS element. This is where the div overlays will go.
        const div = document.createElement('div');

        div.style.width = `${DIV_TOUCH_SIZE}px`;
        div.style.height = `${DIV_TOUCH_SIZE}px`;
        div.style.position = 'absolute';
        div.style.top = `${DIV_TOUCH_POS_X}px`;
        div.style.left = `${DIV_TOUCH_POS_Y}px`;
        div.style.zIndex = DIV_TOUCH_ZINDEX.toString();

        this._div = div;
        this._renderer = renderer;

        /**
         * pre-bind the functions
         * @type {Function}
         * @private
         */
        this._onKeyDown = this._onKeyDown.bind(this);

        /**
         * pre-bind the functions
         * @type {Function}
         * @private
         */
        this._onMouseMove = this._onMouseMove.bind(this);

        // let listen for tab.. once pressed we can fire up and show the accessibility layer
        globalThis.addEventListener('keydown', this._onKeyDown, false);
    }

    /**
     * Value of `true` if accessibility is currently active and accessibility layers are showing.
     * @member {boolean}
     * @readonly
     */
    get isActive(): boolean
    {
        return this._isActive;
    }

    /**
     * Value of `true` if accessibility is enabled for touch devices.
     * @member {boolean}
     * @readonly
     */
    get isMobileAccessibility(): boolean
    {
        return this._isMobileAccessibility;
    }

    get hookDiv()
    {
        return this._hookDiv;
    }

    /**
     * Creates the touch hooks.
     * @private
     */
    private _createTouchHook(): void
    {
        const hookDiv = document.createElement('button');

        hookDiv.style.width = `${DIV_HOOK_SIZE}px`;
        hookDiv.style.height = `${DIV_HOOK_SIZE}px`;
        hookDiv.style.position = 'absolute';
        hookDiv.style.top = `${DIV_HOOK_POS_X}px`;
        hookDiv.style.left = `${DIV_HOOK_POS_Y}px`;
        hookDiv.style.zIndex = DIV_HOOK_ZINDEX.toString();
        hookDiv.style.backgroundColor = '#FF0000';
        hookDiv.title = 'select to enable accessibility for this content';

        hookDiv.addEventListener('focus', () =>
        {
            this._isMobileAccessibility = true;
            this._activate();
            this._destroyTouchHook();
        });

        document.body.appendChild(hookDiv);
        this._hookDiv = hookDiv;
    }

    /**
     * Destroys the touch hooks.
     * @private
     */
    private _destroyTouchHook(): void
    {
        if (!this._hookDiv)
        {
            return;
        }
        document.body.removeChild(this._hookDiv);
        this._hookDiv = null;
    }

    /**
     * Activating will cause the Accessibility layer to be shown.
     * This is called when a user presses the tab key.
     * @private
     */
    private _activate(): void
    {
        if (this._isActive)
        {
            return;
        }

        this._isActive = true;

        globalThis.document.addEventListener('mousemove', this._onMouseMove, true);
        globalThis.removeEventListener('keydown', this._onKeyDown, false);

        this._renderer.runners.postrender.add(this);
        this._renderer.view.canvas.parentNode?.appendChild(this._div);
    }

    /**
     * Deactivating will cause the Accessibility layer to be hidden.
     * This is called when a user moves the mouse.
     * @private
     */
    private _deactivate(): void
    {
        if (!this._isActive || this._isMobileAccessibility)
        {
            return;
        }

        this._isActive = false;

        globalThis.document.removeEventListener('mousemove', this._onMouseMove, true);
        globalThis.addEventListener('keydown', this._onKeyDown, false);

        this._renderer.runners.postrender.remove(this);
        this._div.parentNode?.removeChild(this._div);
    }

    /**
     * This recursive function will run through the scene graph and add any new accessible objects to the DOM layer.
     * @private
     * @param {Container} container - The Container to check.
     */
    private _updateAccessibleObjects(container: Container): void
    {
        if (!container.visible || !container.accessibleChildren)
        {
            return;
        }

        if (container.accessible && container.isInteractive())
        {
            if (!container._accessibleActive)
            {
                this._addChild(container);
            }

            container._renderId = this._renderId;
        }

        const children = container.children;

        if (children)
        {
            for (let i = 0; i < children.length; i++)
            {
                this._updateAccessibleObjects(children[i] as Container);
            }
        }
    }

    /**
     * Runner init called, view is available at this point.
     * @ignore
     */
    public init(options?: AccessibilityOptions)
    {
        this.debug = options?.debug ?? this.debug;
        this._renderer.runners.postrender.remove(this);
    }

    /**
     * Runner postrender was called, ensure that all divs are mapped correctly to their Containers.
     * Only fires while active.
     * @ignore
     */
    public postrender(): void
    {
        /* On Android default web browser, tab order seems to be calculated by position rather than tabIndex,
        *  moving buttons can cause focus to flicker between two buttons making it hard/impossible to navigate,
        *  so I am just running update every half a second, seems to fix it.
        */
        const now = performance.now();

        if (this._mobileInfo.android.device && now < this._androidUpdateCount)
        {
            return;
        }

        this._androidUpdateCount = now + this._androidUpdateFrequency;

        if (!this._renderer.renderingToScreen || !this._renderer.view.canvas)
        {
            return;
        }

        // update children...
        if (this._renderer.lastObjectRendered)
        {
            this._updateAccessibleObjects(this._renderer.lastObjectRendered as Container);
        }

        const { x, y, width, height } = this._renderer.view.canvas.getBoundingClientRect();
        const { width: viewWidth, height: viewHeight, resolution } = this._renderer;

        const sx = (width / viewWidth) * resolution;
        const sy = (height / viewHeight) * resolution;

        let div = this._div;

        div.style.left = `${x}px`;
        div.style.top = `${y}px`;
        div.style.width = `${viewWidth}px`;
        div.style.height = `${viewHeight}px`;

        for (let i = 0; i < this._children.length; i++)
        {
            const child = this._children[i];

            if (child._renderId !== this._renderId)
            {
                child._accessibleActive = false;

                removeItems(this._children, i, 1);
                this._div.removeChild(child._accessibleDiv);
                this._pool.push(child._accessibleDiv);
                child._accessibleDiv = null;

                i--;
            }
            else
            {
                // map div to display..
                div = child._accessibleDiv;
                let hitArea = child.hitArea as Rectangle;
                const wt = child.worldTransform;

                if (child.hitArea)
                {
                    div.style.left = `${(wt.tx + (hitArea.x * wt.a)) * sx}px`;
                    div.style.top = `${(wt.ty + (hitArea.y * wt.d)) * sy}px`;

                    div.style.width = `${hitArea.width * wt.a * sx}px`;
                    div.style.height = `${hitArea.height * wt.d * sy}px`;
                }
                else
                {
                    hitArea = child.getBounds().rectangle;

                    this._capHitArea(hitArea);

                    div.style.left = `${hitArea.x * sx}px`;
                    div.style.top = `${hitArea.y * sy}px`;

                    div.style.width = `${hitArea.width * sx}px`;
                    div.style.height = `${hitArea.height * sy}px`;

                    // update button titles and hints if they exist and they've changed
                    if (div.title !== child.accessibleTitle && child.accessibleTitle !== null)
                    {
                        div.title = child.accessibleTitle || '';
                    }
                    if (div.getAttribute('aria-label') !== child.accessibleHint
                        && child.accessibleHint !== null)
                    {
                        div.setAttribute('aria-label', child.accessibleHint || '');
                    }
                }

                // the title or index may have changed, if so lets update it!
                if (child.accessibleTitle !== div.title || child.tabIndex !== div.tabIndex)
                {
                    div.title = child.accessibleTitle || '';
                    div.tabIndex = child.tabIndex;
                    if (this.debug)
                    {
                        this._updateDebugHTML(div);
                    }
                }
            }
        }

        // increment the render id..
        this._renderId++;
    }

    /**
     * private function that will visually add the information to the
     * accessibility div
     * @param {HTMLElement} div -
     */
    private _updateDebugHTML(div: AccessibleHTMLElement): void
    {
        div.innerHTML = `type: ${div.type}</br> title : ${div.title}</br> tabIndex: ${div.tabIndex}`;
    }

    /**
     * Adjust the hit area based on the bounds of a display object
     * @param {Rectangle} hitArea - Bounds of the child
     */
    private _capHitArea(hitArea: Rectangle): void
    {
        if (hitArea.x < 0)
        {
            hitArea.width += hitArea.x;
            hitArea.x = 0;
        }

        if (hitArea.y < 0)
        {
            hitArea.height += hitArea.y;
            hitArea.y = 0;
        }

        const { width: viewWidth, height: viewHeight } = this._renderer;

        if (hitArea.x + hitArea.width > viewWidth)
        {
            hitArea.width = viewWidth - hitArea.x;
        }

        if (hitArea.y + hitArea.height > viewHeight)
        {
            hitArea.height = viewHeight - hitArea.y;
        }
    }

    /**
     * Adds a Container to the accessibility manager
     * @private
     * @param {Container} container - The child to make accessible.
     */
    private _addChild<T extends Container>(container: T): void
    {
        //    this.activate();

        let div = this._pool.pop();

        if (!div)
        {
            div = document.createElement('button');

            div.style.width = `${DIV_TOUCH_SIZE}px`;
            div.style.height = `${DIV_TOUCH_SIZE}px`;
            div.style.backgroundColor = this.debug ? 'rgba(255,255,255,0.5)' : 'transparent';
            div.style.position = 'absolute';
            div.style.zIndex = DIV_TOUCH_ZINDEX.toString();
            div.style.borderStyle = 'none';

            // ARIA attributes ensure that button title and hint updates are announced properly
            if (navigator.userAgent.toLowerCase().includes('chrome'))
            {
                // Chrome doesn't need aria-live to work as intended; in fact it just gets more confused.
                div.setAttribute('aria-live', 'off');
            }
            else
            {
                div.setAttribute('aria-live', 'polite');
            }

            if (navigator.userAgent.match(/rv:.*Gecko\//))
            {
                // FireFox needs this to announce only the new button name
                div.setAttribute('aria-relevant', 'additions');
            }
            else
            {
                // required by IE, other browsers don't much care
                div.setAttribute('aria-relevant', 'text');
            }

            div.addEventListener('click', this._onClick.bind(this));
            div.addEventListener('focus', this._onFocus.bind(this));
            div.addEventListener('focusout', this._onFocusOut.bind(this));
        }

        // set pointer events
        div.style.pointerEvents = container.accessiblePointerEvents;
        // set the type, this defaults to button!
        div.type = container.accessibleType;

        if (container.accessibleTitle && container.accessibleTitle !== null)
        {
            div.title = container.accessibleTitle;
        }
        else if (!container.accessibleHint
            || container.accessibleHint === null)
        {
            div.title = `container ${container.tabIndex}`;
        }

        if (container.accessibleHint
            && container.accessibleHint !== null)
        {
            div.setAttribute('aria-label', container.accessibleHint);
        }

        if (this.debug)
        {
            this._updateDebugHTML(div);
        }

        container._accessibleActive = true;
        container._accessibleDiv = div;
        div.container = container;

        this._children.push(container);
        this._div.appendChild(container._accessibleDiv);
        container._accessibleDiv.tabIndex = container.tabIndex;
    }

    /**
     * Dispatch events with the EventSystem.
     * @param e
     * @param type
     * @private
     */
    private _dispatchEvent(e: UIEvent, type: string[]): void
    {
        const { container: target } = e.target as AccessibleHTMLElement;
        const boundary = this._renderer.events.rootBoundary;
        const event: FederatedEvent = Object.assign(new FederatedEvent(boundary), { target });

        boundary.rootTarget = this._renderer.lastObjectRendered as Container;
        type.forEach((type) => boundary.dispatchEvent(event, type));
    }

    /**
     * Maps the div button press to pixi's EventSystem (click)
     * @private
     * @param {MouseEvent} e - The click event.
     */
    private _onClick(e: MouseEvent): void
    {
        this._dispatchEvent(e, ['click', 'pointertap', 'tap']);
    }

    /**
     * Maps the div focus events to pixi's EventSystem (mouseover)
     * @private
     * @param {FocusEvent} e - The focus event.
     */
    private _onFocus(e: FocusEvent): void
    {
        if (!(e.target as Element).getAttribute('aria-live'))
        {
            (e.target as Element).setAttribute('aria-live', 'assertive');
        }

        this._dispatchEvent(e, ['mouseover']);
    }

    /**
     * Maps the div focus events to pixi's EventSystem (mouseout)
     * @private
     * @param {FocusEvent} e - The focusout event.
     */
    private _onFocusOut(e: FocusEvent): void
    {
        if (!(e.target as Element).getAttribute('aria-live'))
        {
            (e.target as Element).setAttribute('aria-live', 'polite');
        }

        this._dispatchEvent(e, ['mouseout']);
    }

    /**
     * Is called when a key is pressed
     * @private
     * @param {KeyboardEvent} e - The keydown event.
     */
    private _onKeyDown(e: KeyboardEvent): void
    {
        if (e.keyCode !== KEY_CODE_TAB)
        {
            return;
        }

        this._activate();
    }

    /**
     * Is called when the mouse moves across the renderer element
     * @private
     * @param {MouseEvent} e - The mouse event.
     */
    private _onMouseMove(e: MouseEvent): void
    {
        if (e.movementX === 0 && e.movementY === 0)
        {
            return;
        }

        this._deactivate();
    }

    /** Destroys the accessibility manager */
    public destroy(): void
    {
        this._destroyTouchHook();
        this._div = null;

        globalThis.document.removeEventListener('mousemove', this._onMouseMove, true);
        globalThis.removeEventListener('keydown', this._onKeyDown);

        this._pool = null;
        this._children = null;
        this._renderer = null;
    }
}