feat(focus-trap): add the ability to specify a focus target

Adds the ability to specify an element that should take precedence over other focusable elements inside of a focus trap.

Fixes angular#1468.

src/lib/core/a11y/focus-trap.spec.ts

@@ -6,24 +6,21 @@ import {InteractivityChecker} from './interactivity-checker';
 
 
 describe('FocusTrap', () => {
-  let checker: InteractivityChecker;
-  let fixture: ComponentFixture<FocusTrapTestApp>;
-
   describe('with default element', () => {
+    let fixture: ComponentFixture<FocusTrapTestApp>;
+    let focusTrapInstance: FocusTrap;
+
     beforeEach(() => TestBed.configureTestingModule({
       declarations: [FocusTrap, FocusTrapTestApp],
       providers: [InteractivityChecker]
     }));
 
     beforeEach(inject([InteractivityChecker], (c: InteractivityChecker) => {
-      checker = c;
       fixture = TestBed.createComponent(FocusTrapTestApp);
+      focusTrapInstance = fixture.debugElement.query(By.directive(FocusTrap)).componentInstance;
     }));
 
     it('wrap focus from end to start', () => {
-      let focusTrap = fixture.debugElement.query(By.directive(FocusTrap));
-      let focusTrapInstance = focusTrap.componentInstance as FocusTrap;
-
       // Because we can't mimic a real tab press focus change in a unit test, just call the
       // focus event handler directly.
       focusTrapInstance.focusFirstTabbableElement();
@@ -33,9 +30,6 @@ describe('FocusTrap', () => {
     });
 
     it('should wrap focus from start to end', () => {
-      let focusTrap = fixture.debugElement.query(By.directive(FocusTrap));
-      let focusTrapInstance = focusTrap.componentInstance as FocusTrap;
-
       // Because we can't mimic a real tab press focus change in a unit test, just call the
       // focus event handler directly.
       focusTrapInstance.focusLastTabbableElement();
@@ -44,6 +38,35 @@ describe('FocusTrap', () => {
           .toBe('button', 'Expected button element to be focused');
     });
   });
+
+  describe('with focus targets', () => {
+    let fixture: ComponentFixture<FocusTrapTargetTestApp>;
+    let focusTrapInstance: FocusTrap;
+
+    beforeEach(() => TestBed.configureTestingModule({
+      declarations: [FocusTrap, FocusTrapTargetTestApp],
+      providers: [InteractivityChecker]
+    }));
+
+    beforeEach(inject([InteractivityChecker], (c: InteractivityChecker) => {
+      fixture = TestBed.createComponent(FocusTrapTargetTestApp);
+      focusTrapInstance = fixture.debugElement.query(By.directive(FocusTrap)).componentInstance;
+    }));
+
+    it('should be able to prioritize the first focus target', () => {
+      // Because we can't mimic a real tab press focus change in a unit test, just call the
+      // focus event handler directly.
+      focusTrapInstance.focusFirstTabbableElement();
+      expect(document.activeElement.id).toBe('first');
+    });
+
+    it('should be able to prioritize the last focus target', () => {
+      // Because we can't mimic a real tab press focus change in a unit test, just call the
+      // focus event handler directly.
+      focusTrapInstance.focusLastTabbableElement();
+      expect(document.activeElement.id).toBe('last');
+    });
+  });
 });
 
 
@@ -56,3 +79,16 @@ describe('FocusTrap', () => {
     `
 })
 class FocusTrapTestApp { }
+
+
+@Component({
+  template: `
+    <focus-trap>
+      <input>
+      <button id="first" md-focus-target>SAVE</button>
+      <button id="last" md-focus-target></button>
+      <input>
+    </focus-trap>
+    `
+})
+class FocusTrapTargetTestApp { }

src/lib/core/a11y/focus-trap.ts

@@ -1,6 +1,8 @@
 import {Component, ViewEncapsulation, ViewChild, ElementRef} from '@angular/core';
 import {InteractivityChecker} from './interactivity-checker';
 
+/** Selector for nodes that should have a higher priority when looking for focus targets. */
+const FOCUS_TARGET_SELECTOR = '[md-focus-target]';
 
 /**
  * Directive for trapping focus within a region.
@@ -47,6 +49,12 @@ export class FocusTrap {
       return root;
     }
 
+    let focusTarget = root.querySelector(FOCUS_TARGET_SELECTOR) as HTMLElement;
+
+    if (focusTarget) {
+      return focusTarget;
+    }
+
     // Iterate in DOM order.
     let childCount = root.children.length;
     for (let i = 0; i < childCount; i++) {
@@ -65,6 +73,12 @@ export class FocusTrap {
       return root;
     }
 
+    let focusTargets = root.querySelectorAll(FOCUS_TARGET_SELECTOR);
+
+    if (focusTargets.length) {
+      return focusTargets[focusTargets.length - 1] as HTMLElement;
+    }
+
     // Iterate in reverse DOM order.
     for (let i = root.children.length - 1; i >= 0; i--) {
       let tabbableChild = this._getLastTabbableElement(root.children[i] as HTMLElement);