Add a focus indicator utility to help improve a11y debugging.

PiperOrigin-RevId: 225080476

Author: cissyshi

angular_components/lib/model/a11y/focus_indicator_controller.dart

@@ -0,0 +1,126 @@
+// Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:async';
+import 'dart:html';
+
+import 'package:angular/di.dart';
+
+const focusIndicatorProviders = [
+  FactoryProvider(
+      FocusIndicatorController, createFocusIndicatorControllerIfNotAvailable)
+];
+
+@Injectable()
+FocusIndicatorController createFocusIndicatorControllerIfNotAvailable(
+        @Optional() @SkipSelf() FocusIndicatorController controller) =>
+    controller ?? FocusIndicatorController();
+
+/// Utility that attaches an a focus indicator to the page when enabled.
+///
+/// Only used to improve a11y debugging experience. DO NOT USE IN PRODUCTION!
+class FocusIndicatorController {
+  Element _focusIndicator;
+  int _repositionLoopId;
+
+  Element _activeElement;
+  Element get activeElement => _activeElement;
+
+  bool _enabled = false;
+  bool get enabled => _enabled;
+
+  set enabled(bool value) {
+    if (_enabled == value) return;
+    _enabled = value;
+    if (_enabled) {
+      _turnOnKeyNavMode();
+    } else {
+      _turnOffKeyNavMode();
+    }
+  }
+
+  void _turnOnKeyNavMode() {
+    window.addEventListener('focus', _onFocus, true);
+    window.addEventListener('blur', _onBlur, true);
+
+    _activeElement = document.activeElement;
+
+    _focusIndicator = document.createElement('div');
+    _focusIndicator.id = 'acx-focus-indicator';
+    _focusIndicator.style.position = 'fixed';
+    _focusIndicator.style.zIndex = '9999';
+    _focusIndicator.style.outline = '2px solid #ff9800';
+    _focusIndicator.style.pointerEvents = 'none';
+    document.body.append(_focusIndicator);
+
+    _startRepositionLoop();
+  }
+
+  void _turnOffKeyNavMode() {
+    window.removeEventListener('focus', _onFocus, true);
+    window.removeEventListener('blur', _onBlur, true);
+
+    _activeElement = null;
+
+    if (_focusIndicator != null) {
+      _focusIndicator.remove();
+      _focusIndicator = null;
+    }
+
+    _cancelRepositionLoop();
+  }
+
+  void _onFocus(Event event) {
+    _updateActiveElement(event);
+  }
+
+  void _onBlur(Event event) {
+    Timer.run(() {
+      _updateActiveElement(event);
+    });
+  }
+
+  void _updateActiveElement(Event event) {
+    if (!_enabled || _activeElement == document.activeElement) return;
+
+    if (_activeElement != null) {
+      _activeElement.style.outline = '';
+      if (_activeElement.getAttribute('style')?.isEmpty == true) {
+        _activeElement.attributes.remove('style');
+      }
+    }
+
+    _activeElement = document.activeElement;
+
+    window.console.groupCollapsed('Active element '
+        '[${_activeElement.tagName.toLowerCase()}] '
+        'after "${event.type}"');
+    window.console.log(_activeElement);
+    window.console.log(event);
+    window.console.groupEnd();
+
+    _activeElement.style.outline = 'none';
+  }
+
+  void _startRepositionLoop() {
+    _repositionLoopId = window.requestAnimationFrame(_reposition);
+  }
+
+  void _cancelRepositionLoop() {
+    if (_repositionLoopId != null) {
+      window.cancelAnimationFrame(_repositionLoopId);
+      _repositionLoopId = null;
+    }
+  }
+
+  void _reposition(_) {
+    var rect = _activeElement.getBoundingClientRect();
+    _focusIndicator.style.top = '${rect.top}px';
+    _focusIndicator.style.left = '${rect.left}px';
+    _focusIndicator.style.width = '${rect.width}px';
+    _focusIndicator.style.height = '${rect.height}px';
+
+    _startRepositionLoop();
+  }
+}

angular_gallery/lib/builder/template/gallery.dart.mustache

@@ -8,11 +8,13 @@ import 'package:angular_components/content/deferred_content.dart';
 import 'package:angular_components/focus/focus.dart';
 import 'package:angular_components/highlighted_text/highlighted_value.dart';
 import 'package:angular_components/material_button/material_button.dart';
+import 'package:angular_components/material_checkbox/material_checkbox.dart';
 import 'package:angular_components/material_icon/material_icon.dart';
 import 'package:angular_components/material_list/material_list.dart';
 import 'package:angular_components/material_list/material_list_item.dart';
 import 'package:angular_components/material_select/material_select_searchbox.dart';
 import 'package:angular_components/model/selection/string_selection_options.dart';
+import 'package:angular_components/model/a11y/focus_indicator_controller.dart';
 import 'package:angular_components/model/ui/has_renderer.dart';
 import 'package:angular_components/model/ui/highlight_assistant.dart';
 import 'package:angular_components/model/ui/highlight_provider.dart';
@@ -28,6 +30,7 @@ import 'gallery_route_library.dart';
       DeferredContentDirective,
       HighlightedValueComponent,
       MaterialButtonComponent,
+      MaterialCheckboxComponent,
       MaterialIconComponent,
       MaterialListComponent,
       MaterialListItemComponent,
@@ -38,6 +41,7 @@ import 'gallery_route_library.dart';
       NgModel,
       routerDirectives,
     ],
+    providers: [focusIndicatorProviders],
     viewProviders: [
       Provider(HighlightProvider, useExisting: GalleryComponent)
     ],
@@ -53,10 +57,11 @@ class GalleryComponent implements HighlightProvider {
   final ItemRenderer _highlightRenderer =
       (item) => item is _Example ? item.displayName : item?.toString();
   final List<RouteDefinition> routes = galleryRoutes;
+  final FocusIndicatorController focusIndicatorController;
   StringSelectionOptions<_Example> exampleOptions;
   String _breadcrumb = '';
 
-  GalleryComponent(Router router) {
+  GalleryComponent(this.focusIndicatorController, Router router) {
     router.stream.listen((newRoute) {
         _breadcrumb = breadcrumbs[newRoute.path];
         querySelector('material-content').scrollTop = 0;

angular_gallery/lib/builder/template/gallery.html.mustache

@@ -38,6 +38,11 @@
           {{ breadcrumb }}
         </span>
       </div>
+      <div class="key-nav">
+        <material-checkbox [(checked)]="focusIndicatorController.enabled">
+          Enable focus indicator
+        </material-checkbox>
+      </div>
     </header>
     <router-outlet [routes]="routes"></router-outlet>
   </div>

angular_gallery/lib/builder/template/gallery.scss.mustache

@@ -2,6 +2,7 @@
 @import 'package:angular_components/css/material/material';
 @import 'package:angular_components/css/material/mixins';
 @import 'package:angular_components/css/material/shadow';
+@import 'package:angular_components/material_checkbox/mixins';
 @import 'package:angular_components/material_input/mixins';
 
 material-drawer {
@@ -61,5 +62,12 @@ material-content {
     position: sticky;
     top: 0;
     z-index: 1;
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+    padding-right: $mat-grid * 5;
+
+    @include material-checkbox-color($mat-orange-500);
   }
 }

angular_gallery_section/lib/builder/template/gallery_section.dart.mustache

@@ -1,5 +1,6 @@
 import 'package:angular/angular.dart';
 import 'package:angular_components/laminate/popup/module.dart';
+import 'package:angular_components/model/a11y/focus_indicator_controller.dart';
 
 // Import each demo.
 {{#imports}}
@@ -15,17 +16,28 @@ final _showDocs = Uri.base.queryParameters['showDocs'];
 
 @Component(
   selector: 'gallery-section',
-  providers: [popupBindings],
+  providers: [focusIndicatorProviders, popupBindings],
   template: r'''
+  <a class="focus-indicator-toggle"
+      tabindex="0"
+      (click)="focusIndicatorController.enabled = !focusIndicatorController.enabled">
+    <template [ngIf]="!focusIndicatorController.enabled">
+      Enable focus indicator
+    </template>
+    <template [ngIf]="focusIndicatorController.enabled">
+      Disable focus indicator
+    </template>
+  </a>
   <div *ngIf="!showDocsPage">
-    <div class="docs-toggle" (click)="toggleDocsPage()">Show Gallery Page</div>
+    <a class="docs-toggle" tabindex="0"
+        (click)="toggleDocsPage()">Show Gallery Page</a>
       {{#demos}}
       <{{selector}}></{{selector}}>
       {{/demos}}
   </div>
   <div *ngIf="showDocsPage">
-    <div class="docs-toggle" *ngIf="!paramShowDocs"
-        (click)="toggleDocsPage()">Show Demo Only</div>
+    <a class="docs-toggle" tabindex="0" *ngIf="!paramShowDocs"
+        (click)="toggleDocsPage()">Show Demo Only</a>
       {{#apis}}
       {{#docs}}
       <{{selector}}></{{selector}}>
@@ -43,11 +55,21 @@ final _showDocs = Uri.base.queryParameters['showDocs'];
     {{/docs}}
     {{/apis}}
   ],
-  styles: ['.docs-toggle {color: #4285f4; cursor: pointer;}'],
+  styles: ['''
+    .focus-indicator-toggle,
+    .docs-toggle {
+      color: #4285f4;
+      cursor: pointer;
+    }
+  '''],
 )
 class GallerySection {
+  final FocusIndicatorController focusIndicatorController;
+
   bool get paramShowDocs => _showDocs != null;
   bool _showDocsPage = _showDocs != null;
   bool get showDocsPage => _showDocsPage;
   void toggleDocsPage() => _showDocsPage = !showDocsPage;
+
+  GallerySection(this.focusIndicatorController);
 }