Add a focusin event that bubbles when focus changes

[mbarlow12]

After the changes from phetsims/scenery-phet@2eead2b, phetsims/scenery-phet@cb7d61c, and phetsims/scenery-phet@eeb182f, I discovered that we can no longer add event listeners (at least for focus) to NumberControls or composite components that use NumberControl.

For example, the following produces no output:

const numberControl = new NumberControl( ... );
numberControl.addInputListener( {
  focus: e => { console.log( 'numberControl focused' ); }
} );

however, within NumberControl, we can add a focus listener onto the Slider component that will be called.

@jessegreenberg and I tracked this down to the fact that we're not bubbling focus events in the scene graph. From the focusinEmitter in Input.js:

this.dispatchEvent( trail, 'focus', this.a11yPointer, event, false );

Essentially, the slider is triggering the focus event, but Scenery doesn't dispatch the event to the parent nodes.

We discussed 2 options for a fix:

1. handling all focus events identically in the scene graph and allowing them to bubble, or
2. adding a second focusin input event that would bubble

The main issue with option 1 is that there may be cases where allowing focus to bubble in all cases could either cause unanticipated behavior or lead to performance issues (e.g. for deeply nested nodes, checking for listeners on all parents could be an issue).

The second case would complicate the a11y API but would also mimic the DOM spec.

[mbarlow12]

My inclination is to go with option 1 as it's a simple boolean switch. Additionally, since we're only using the focusin browser event, you could argue that Scenery is only aware of a bubbling focus event, so that would maintain consistent behavior between the PDOM and Scenery.

[jessegreenberg]

I am on the fence. I agree that it will be easy for devs to forget that there is both focus and a focusin event. But after thinking about it more, I realized there may still be benefit to having both.

Lets say that focus bubbles and the NumberControl catches that event when its HSlider gets focus. In that case, NumberControl's primary sibling will NOT equal document.activeElement, it does not have focus. It seems strange that it would then trigger focus callbacks.

[jessegreenberg]

Because of the above, I am leaning toward option 2, but would be good to discuss again at dev meeting.

[mbarlow12]

@jessegreenberg would the advantage of using a focusin event be that the parent node would be aware that one of it's children is receiving focus vs receiving focus itself?

[jessegreenberg]

Exactly! Thats what I was going for in the example in #920 (comment)

[jessegreenberg]

Discussed during 1/7/19 dev meeting:

We will proceed with supporting both focus event and focusin event. We discussed just using focusin as well for clarity, but didn't want to limit ourselves to this as we may have cases in the future where we do not want a focus event that bubbles.

[mbarlow12]

• add the following to Input.js

// DOM spec is that focus events do not bubble while focusin events do
// allows for parents/composite Nodes to add listeners when children recieve focus
this.dispatchEvent( trail, 'focus', this.a11yPointer, event, false );
this.dispatchEvent( trail, 'focusin', this.a11yPointer, event, true );

• test the bejesus out of it

[zepumph]

Ideally we will add this change before the next developer meeting. Marking high priority.

[jessegreenberg]

We need to get through #921 before we can finish this, marking this on-hold.

[zepumph]

The usage that originally caused this issue is no longer in the project. I think that we should close this issue. I'll meet you all over in #921