devtools/client/accessibility/accessibility-proxy.js

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 "use strict";
   6
   7 loader.lazyRequireGetter(
   8   this,
   9   "CombinedProgress",
  10   "resource://devtools/client/accessibility/utils/audit.js",
  11   true
  12 );
  13
  14 const {
  15   accessibility: { AUDIT_TYPE },
  16 } = require("resource://devtools/shared/constants.js");
  17 const {
  18   FILTERS,
  19 } = require("resource://devtools/client/accessibility/constants.js");
  20
  21 /**
  22  * Component responsible for tracking all Accessibility fronts in parent and
  23  * content processes.
  24  */
  25 class AccessibilityProxy {
  26   #panel;
  27   #initialized;
  28   constructor(commands, panel) {
  29     this.commands = commands;
  30     this.#panel = panel;
  31
  32     this.#initialized = false;
  33     this._accessibilityWalkerFronts = new Set();
  34     this.lifecycleEvents = new Map();
  35     this.accessibilityEvents = new Map();
  36
  37     this.audit = this.audit.bind(this);
  38     this.enableAccessibility = this.enableAccessibility.bind(this);
  39     this.getAccessibilityTreeRoot = this.getAccessibilityTreeRoot.bind(this);
  40     this.resetAccessiblity = this.resetAccessiblity.bind(this);
  41     this.startListeningForAccessibilityEvents =
  42       this.startListeningForAccessibilityEvents.bind(this);
  43     this.startListeningForLifecycleEvents =
  44       this.startListeningForLifecycleEvents.bind(this);
  45     this.startListeningForParentLifecycleEvents =
  46       this.startListeningForParentLifecycleEvents.bind(this);
  47     this.stopListeningForAccessibilityEvents =
  48       this.stopListeningForAccessibilityEvents.bind(this);
  49     this.stopListeningForLifecycleEvents =
  50       this.stopListeningForLifecycleEvents.bind(this);
  51     this.stopListeningForParentLifecycleEvents =
  52       this.stopListeningForParentLifecycleEvents.bind(this);
  53     this.highlightAccessible = this.highlightAccessible.bind(this);
  54     this.unhighlightAccessible = this.unhighlightAccessible.bind(this);
  55     this.onTargetAvailable = this.onTargetAvailable.bind(this);
  56     this.onTargetDestroyed = this.onTargetDestroyed.bind(this);
  57     this.onTargetSelected = this.onTargetSelected.bind(this);
  58     this.onAccessibilityFrontAvailable =
  59       this.onAccessibilityFrontAvailable.bind(this);
  60     this.onAccessibilityFrontDestroyed =
  61       this.onAccessibilityFrontDestroyed.bind(this);
  62     this.onAccessibleWalkerFrontAvailable =
  63       this.onAccessibleWalkerFrontAvailable.bind(this);
  64     this.onAccessibleWalkerFrontDestroyed =
  65       this.onAccessibleWalkerFrontDestroyed.bind(this);
  66     this.unhighlightBeforeCalling = this.unhighlightBeforeCalling.bind(this);
  67     this.toggleDisplayTabbingOrder = this.toggleDisplayTabbingOrder.bind(this);
  68   }
  69
  70   get enabled() {
  71     return this.accessibilityFront && this.accessibilityFront.enabled;
  72   }
  73
  74   /**
  75    * Indicates whether the accessibility service is enabled.
  76    */
  77   get canBeEnabled() {
  78     return this.parentAccessibilityFront.canBeEnabled;
  79   }
  80
  81   get currentTarget() {
  82     return this.commands.targetCommand.selectedTargetFront;
  83   }
  84
  85   /**
  86    * Perform an audit for a given filter.
  87    *
  88    * @param  {String} filter
  89    *         Type of an audit to perform.
  90    * @param  {Function} onProgress
  91    *         Audit progress callback.
  92    *
  93    * @return {Promise}
  94    *         Resolves when the audit for every document, that each of the frame
  95    *         accessibility walkers traverse, completes.
  96    */
  97   async audit(filter, onProgress) {
  98     const types = filter === FILTERS.ALL ? Object.values(AUDIT_TYPE) : [filter];
  99
 100     const targetTypes = [this.commands.targetCommand.TYPES.FRAME];
 101     const targets =
 102       await this.commands.targetCommand.getAllTargetsInSelectedTargetTree(
 103         targetTypes
 104       );
 105
 106     const progress = new CombinedProgress({
 107       onProgress,
 108       totalFrames: targets.length,
 109     });
 110     const audits = await this.withAllAccessibilityWalkerFronts(
 111       async accessibleWalkerFront =>
 112         accessibleWalkerFront.audit({
 113           types,
 114           onProgress: progress.onProgressForWalker.bind(
 115             progress,
 116             accessibleWalkerFront
 117           ),
 118           // If a frame was selected in the iframe picker, we don't want to retrieve the
 119           // ancestries at it would mess with the tree structure and would make it misbehave.
 120           retrieveAncestries:
 121             this.commands.targetCommand.isTopLevelTargetSelected(),
 122         })
 123     );
 124
 125     // Accumulate all audits into a single structure.
 126     const combinedAudit = { ancestries: [] };
 127     for (const audit of audits) {
 128       // If any of the audits resulted in an error, no need to continue.
 129       if (audit.error) {
 130         return audit;
 131       }
 132
 133       combinedAudit.ancestries.push(...audit.ancestries);
 134     }
 135
 136     return combinedAudit;
 137   }
 138
 139   async toggleDisplayTabbingOrder(displayTabbingOrder) {
 140     if (displayTabbingOrder) {
 141       const { walker: domWalkerFront } =
 142         await this.currentTarget.getFront("inspector");
 143       await this.accessibilityFront.accessibleWalkerFront.showTabbingOrder(
 144         await domWalkerFront.getRootNode(),
 145         0
 146       );
 147     } else {
 148       // we don't want to use withAllAccessibilityWalkerFronts as it only acts on selected
 149       // target tree, and we want to hide _all_ highlighters.
 150       const accessibilityFronts =
 151         await this.commands.targetCommand.getAllFronts(
 152           [this.commands.targetCommand.TYPES.FRAME],
 153           "accessibility"
 154         );
 155       await Promise.all(
 156         accessibilityFronts.map(accessibilityFront =>
 157           accessibilityFront.accessibleWalkerFront.hideTabbingOrder()
 158         )
 159       );
 160     }
 161   }
 162
 163   async enableAccessibility() {
 164     // Accessibility service is initialized using the parent accessibility
 165     // front. That, in turn, initializes accessibility service in all content
 166     // processes. We need to wait until that happens to be sure platform
 167     // accessibility is fully enabled.
 168     const enabled = this.accessibilityFront.once("init");
 169     await this.parentAccessibilityFront.enable();
 170     await enabled;
 171   }
 172
 173   /**
 174    * Return the topmost level accessibility walker to be used as the root of
 175    * the accessibility tree view.
 176    *
 177    * @return {Object}
 178    *         Topmost accessibility walker.
 179    */
 180   getAccessibilityTreeRoot() {
 181     return this.accessibilityFront.accessibleWalkerFront;
 182   }
 183
 184   /**
 185    * Look up accessibility fronts (get an existing one or create a new one) for
 186    * all existing target fronts and run a task with each one of them.
 187    * @param {Function} task
 188    *        Function to execute with each accessiblity front.
 189    */
 190   async withAllAccessibilityFronts(taskFn) {
 191     const accessibilityFronts = await this.commands.targetCommand.getAllFronts(
 192       [this.commands.targetCommand.TYPES.FRAME],
 193       "accessibility",
 194       {
 195         // only get the fronts for the selected frame tree, in case a specific document
 196         // is selected in the iframe picker (if not, the top-level target is considered
 197         // as the selected target)
 198         onlyInSelectedTargetTree: true,
 199       }
 200     );
 201     const tasks = [];
 202     for (const accessibilityFront of accessibilityFronts) {
 203       tasks.push(taskFn(accessibilityFront));
 204     }
 205
 206     return Promise.all(tasks);
 207   }
 208
 209   /**
 210    * Look up accessibility walker fronts (get an existing one or create a new
 211    * one using accessibility front) for all existing target fronts and run a
 212    * task with each one of them.
 213    * @param {Function} task
 214    *        Function to execute with each accessiblity walker front.
 215    */
 216   withAllAccessibilityWalkerFronts(taskFn) {
 217     return this.withAllAccessibilityFronts(async accessibilityFront =>
 218       taskFn(accessibilityFront.accessibleWalkerFront)
 219     );
 220   }
 221
 222   /**
 223    * Unhighlight previous accessible object if we switched between processes and
 224    * call the appropriate event handler.
 225    */
 226   unhighlightBeforeCalling(listener) {
 227     return async accessible => {
 228       if (accessible) {
 229         const accessibleWalkerFront = accessible.getParent();
 230         if (this._currentAccessibleWalkerFront !== accessibleWalkerFront) {
 231           if (this._currentAccessibleWalkerFront) {
 232             await this._currentAccessibleWalkerFront.unhighlight();
 233           }
 234
 235           this._currentAccessibleWalkerFront = accessibleWalkerFront;
 236         }
 237       }
 238
 239       await listener(accessible);
 240     };
 241   }
 242
 243   /**
 244    * Start picking and add walker listeners.
 245    * @param  {Boolean} doFocus
 246    *         If true, move keyboard focus into content.
 247    */
 248   pick(doFocus, onHovered, onPicked, onPreviewed, onCanceled) {
 249     return this.withAllAccessibilityWalkerFronts(
 250       async accessibleWalkerFront => {
 251         this.startListening(accessibleWalkerFront, {
 252           events: {
 253             "picker-accessible-hovered":
 254               this.unhighlightBeforeCalling(onHovered),
 255             "picker-accessible-picked": this.unhighlightBeforeCalling(onPicked),
 256             "picker-accessible-previewed":
 257               this.unhighlightBeforeCalling(onPreviewed),
 258             "picker-accessible-canceled":
 259               this.unhighlightBeforeCalling(onCanceled),
 260           },
 261           // Only register listeners once (for top level), no need to register
 262           // them for all walkers again and again.
 263           register: accessibleWalkerFront.targetFront.isTopLevel,
 264         });
 265         await accessibleWalkerFront.pick(
 266           // Only pass doFocus to the top level accessibility walker front.
 267           doFocus && accessibleWalkerFront.targetFront.isTopLevel
 268         );
 269       }
 270     );
 271   }
 272
 273   /**
 274    * Stop picking and remove all walker listeners.
 275    */
 276   async cancelPick() {
 277     this._currentAccessibleWalkerFront = null;
 278     return this.withAllAccessibilityWalkerFronts(
 279       async accessibleWalkerFront => {
 280         await accessibleWalkerFront.cancelPick();
 281         this.stopListening(accessibleWalkerFront, {
 282           events: {
 283             "picker-accessible-hovered": null,
 284             "picker-accessible-picked": null,
 285             "picker-accessible-previewed": null,
 286             "picker-accessible-canceled": null,
 287           },
 288           // Only unregister listeners once (for top level), no need to
 289           // unregister them for all walkers again and again.
 290           unregister: accessibleWalkerFront.targetFront.isTopLevel,
 291         });
 292       }
 293     );
 294   }
 295
 296   async resetAccessiblity() {
 297     const { enabled } = this.accessibilityFront;
 298     const { canBeEnabled, canBeDisabled } = this.parentAccessibilityFront;
 299     return { enabled, canBeDisabled, canBeEnabled };
 300   }
 301
 302   startListening(front, { events, register = false } = {}) {
 303     for (const [type, listener] of Object.entries(events)) {
 304       front.on(type, listener);
 305       if (register) {
 306         this.registerEvent(front, type, listener);
 307       }
 308     }
 309   }
 310
 311   stopListening(front, { events, unregister = false } = {}) {
 312     for (const [type, listener] of Object.entries(events)) {
 313       front.off(type, listener);
 314       if (unregister) {
 315         this.unregisterEvent(front, type, listener);
 316       }
 317     }
 318   }
 319
 320   startListeningForAccessibilityEvents(events) {
 321     for (const accessibleWalkerFront of this._accessibilityWalkerFronts.values()) {
 322       this.startListening(accessibleWalkerFront, {
 323         events,
 324         // Only register listeners once (for top level), no need to register
 325         // them for all walkers again and again.
 326         register: accessibleWalkerFront.targetFront.isTopLevel,
 327       });
 328     }
 329   }
 330
 331   stopListeningForAccessibilityEvents(events) {
 332     for (const accessibleWalkerFront of this._accessibilityWalkerFronts.values()) {
 333       this.stopListening(accessibleWalkerFront, {
 334         events,
 335         // Only unregister listeners once (for top level), no need to unregister
 336         // them for all walkers again and again.
 337         unregister: accessibleWalkerFront.targetFront.isTopLevel,
 338       });
 339     }
 340   }
 341
 342   startListeningForLifecycleEvents(events) {
 343     this.startListening(this.accessibilityFront, { events, register: true });
 344   }
 345
 346   stopListeningForLifecycleEvents(events) {
 347     this.stopListening(this.accessibilityFront, { events, unregister: true });
 348   }
 349
 350   startListeningForParentLifecycleEvents(events) {
 351     this.startListening(this.parentAccessibilityFront, {
 352       events,
 353       register: false,
 354     });
 355   }
 356
 357   stopListeningForParentLifecycleEvents(events) {
 358     this.stopListening(this.parentAccessibilityFront, {
 359       events,
 360       unregister: false,
 361     });
 362   }
 363
 364   highlightAccessible(accessibleFront, options) {
 365     if (!accessibleFront) {
 366       return;
 367     }
 368
 369     const accessibleWalkerFront = accessibleFront.getParent();
 370     if (!accessibleWalkerFront) {
 371       return;
 372     }
 373
 374     accessibleWalkerFront
 375       .highlightAccessible(accessibleFront, options)
 376       .catch(error => {
 377         // Only report an error where there's still a commands instance.
 378         // Ignore cases where toolbox is already destroyed.
 379         if (this.commands) {
 380           console.error(error);
 381         }
 382       });
 383   }
 384
 385   unhighlightAccessible(accessibleFront) {
 386     if (!accessibleFront) {
 387       return;
 388     }
 389
 390     const accessibleWalkerFront = accessibleFront.getParent();
 391     if (!accessibleWalkerFront) {
 392       return;
 393     }
 394
 395     accessibleWalkerFront.unhighlight().catch(error => {
 396       // Only report an error where there's still a commands instance.
 397       // Ignore cases where toolbox is already destroyed.
 398       if (this.commands) {
 399         console.error(error);
 400       }
 401     });
 402   }
 403
 404   async initialize() {
 405     // Initialize it first as it may be used on target selection when calling watchTargets
 406     this.parentAccessibilityFront =
 407       await this.commands.targetCommand.rootFront.getFront(
 408         "parentaccessibility"
 409       );
 410
 411     await this.commands.targetCommand.watchTargets({
 412       types: [this.commands.targetCommand.TYPES.FRAME],
 413       onAvailable: this.onTargetAvailable,
 414       onSelected: this.onTargetSelected,
 415       onDestroyed: this.onTargetDestroyed,
 416     });
 417
 418     // Enable accessibility service if necessary.
 419     if (this.canBeEnabled && !this.enabled) {
 420       await this.enableAccessibility();
 421     }
 422     this.#initialized = true;
 423   }
 424
 425   get supports() {
 426     // Retrieve backward compatibility traits.
 427     // New API's must be described in the "getTraits" method of the AccessibilityActor.
 428     return this.accessibilityFront.traits;
 429   }
 430
 431   destroy() {
 432     this.commands.targetCommand.unwatchTargets({
 433       types: [this.commands.targetCommand.TYPES.FRAME],
 434       onAvailable: this.onTargetAvailable,
 435       onSelected: this.onTargetSelected,
 436       onDestroyed: this.onTargetDestroyed,
 437     });
 438
 439     this.lifecycleEvents.clear();
 440     this.accessibilityEvents.clear();
 441
 442     this.accessibilityFront = null;
 443     this.parentAccessibilityFront = null;
 444     this.simulatorFront = null;
 445     this.simulate = null;
 446     this.commands = null;
 447   }
 448
 449   _getEvents(front) {
 450     return front.typeName === "accessiblewalker"
 451       ? this.accessibilityEvents
 452       : this.lifecycleEvents;
 453   }
 454
 455   registerEvent(front, type, listener) {
 456     const events = this._getEvents(front);
 457     if (events.has(type)) {
 458       events.get(type).add(listener);
 459     } else {
 460       events.set(type, new Set([listener]));
 461     }
 462   }
 463
 464   unregisterEvent(front, type, listener) {
 465     const events = this._getEvents(front);
 466     if (!events.has(type)) {
 467       return;
 468     }
 469
 470     if (!listener) {
 471       events.delete(type);
 472       return;
 473     }
 474
 475     const listeners = events.get(type);
 476     if (listeners.has(listener)) {
 477       listeners.delete(listener);
 478     }
 479
 480     if (!listeners.size) {
 481       events.delete(type);
 482     }
 483   }
 484
 485   onAccessibilityFrontAvailable(accessibilityFront) {
 486     accessibilityFront.watchFronts(
 487       "accessiblewalker",
 488       this.onAccessibleWalkerFrontAvailable,
 489       this.onAccessibleWalkerFrontDestroyed
 490     );
 491   }
 492
 493   onAccessibilityFrontDestroyed(accessibilityFront) {
 494     accessibilityFront.unwatchFronts(
 495       "accessiblewalker",
 496       this.onAccessibleWalkerFrontAvailable,
 497       this.onAccessibleWalkerFrontDestroyed
 498     );
 499   }
 500
 501   onAccessibleWalkerFrontAvailable(accessibleWalkerFront) {
 502     this._accessibilityWalkerFronts.add(accessibleWalkerFront);
 503     // Apply all existing accessible walker front event listeners to the new
 504     // front.
 505     for (const [type, listeners] of this.accessibilityEvents.entries()) {
 506       for (const listener of listeners) {
 507         accessibleWalkerFront.on(type, listener);
 508       }
 509     }
 510   }
 511
 512   onAccessibleWalkerFrontDestroyed(accessibleWalkerFront) {
 513     this._accessibilityWalkerFronts.delete(accessibleWalkerFront);
 514     // Remove all existing accessible walker front event listeners from the
 515     // destroyed front.
 516     for (const [type, listeners] of this.accessibilityEvents.entries()) {
 517       for (const listener of listeners) {
 518         accessibleWalkerFront.off(type, listener);
 519       }
 520     }
 521   }
 522
 523   async onTargetAvailable({ targetFront }) {
 524     targetFront.watchFronts(
 525       "accessibility",
 526       this.onAccessibilityFrontAvailable,
 527       this.onAccessibilityFrontDestroyed
 528     );
 529
 530     if (!targetFront.isTopLevel) {
 531       return;
 532     }
 533
 534     // Clear all the fronts collected by `watchFronts` on the previous set of targets/documents.
 535     this._accessibilityWalkerFronts.clear();
 536   }
 537
 538   async onTargetDestroyed({ targetFront }) {
 539     targetFront.unwatchFronts(
 540       "accessibility",
 541       this.onAccessibilityFrontAvailable,
 542       this.onAccessibilityFrontDestroyed
 543     );
 544   }
 545
 546   async onTargetSelected({ targetFront }) {
 547     this.accessibilityFront = await targetFront.getFront("accessibility");
 548
 549     this.simulatorFront = this.accessibilityFront.simulatorFront;
 550     if (this.simulatorFront) {
 551       this.simulate = types => this.simulatorFront.simulate({ types });
 552     } else {
 553       this.simulate = null;
 554     }
 555
 556     await this.toggleDisplayTabbingOrder(false);
 557
 558     // Move accessibility front lifecycle event listeners to a new top level
 559     // front.
 560     for (const [type, listeners] of this.lifecycleEvents.entries()) {
 561       for (const listener of listeners.values()) {
 562         this.accessibilityFront.on(type, listener);
 563       }
 564     }
 565
 566     // Hold on refreshing the view on initialization.
 567     // This will be done by the Panel class after everything is setup.
 568     // (we especially need to wait for the a11y service to be started)
 569     if (this.#initialized) {
 570       await this.#panel.forceRefresh();
 571     }
 572   }
 573 }
 574
 575 exports.AccessibilityProxy = AccessibilityProxy;