React Events: add onFocusVisibleChange to Focus (#15516)

Called when focus visibility changes. Focus is only considered visible if a
focus event occurs after keyboard navigation. This provides a way for people to
provide visual focus styles for keyboard accessible UIs without those styles
appearing if focus is triggered by mouse, touch, pen.

Author: Nicolas Gallagher

packages/react-events/docs/Focus.md

@@ -1,29 +1,39 @@
 # Focus
 
 The `Focus` module responds to focus and blur events on its child. Focus events
-are dispatched for `mouse`, `pen`, `touch`, and `keyboard`
-pointer types.
+are dispatched for all input types, with the exception of `onFocusVisibleChange`
+which is only dispatched when focusing with a keyboard.
 
 Focus events do not propagate between `Focus` event responders.
 
 ```js
 // Example
-constTextField= (props) => (
-<Focus
- onBlur={props.onBlur}
- onFocus={props.onFocus}
->
-<textarea></textarea>
-</Focus>
-);
+constButton= (props) => {
+const [ focusVisible, setFocusVisible ] =useState(false);
+
+return (
+<Focus
+ onBlur={props.onBlur}
+ onFocus={props.onFocus}
+ onFocusVisibleChange={setFocusVisible}
+>
+<button
+ children={props.children}
+ style={{
+...(focusVisible && focusVisibleStyles)
+ }}
+>
+</Focus>
+ );
+};
 ```
 
 ## Types
 
 ```js
 type FocusEvent = {
  target:Element,
- type:'blur'|'focus'|'focuschange'
+ type:'blur'|'focus'|'focuschange'|'focusvisiblechange'
 }
 ```
 
@@ -43,5 +53,10 @@ Called when the element gains focus.
 
 ### onFocusChange: boolean => void
 
-Called when the element changes hover state (i.e., after `onBlur` and
+Called when the element changes focus state (i.e., after `onBlur` and
 `onFocus`).
+
+### onFocusVisibleChange: boolean => void
+
+Called when the element receives or loses focus following keyboard navigation.
+This can be used to display focus styles only for keyboard interactions.

packages/react-events/src/Focus.js

@@ -19,14 +19,16 @@ type FocusProps = {
 onBlur: (e: FocusEvent)=>void,
 onFocus: (e: FocusEvent)=>void,
 onFocusChange: boolean=>void,
+onFocusVisibleChange: boolean=>void,
 };
 
 typeFocusState={
-isFocused: boolean,
 focusTarget: null|Element|Document,
+isFocused: boolean,
+isLocalFocusVisible: boolean,
 };
 
-typeFocusEventType='focus'|'blur'|'focuschange';
+typeFocusEventType='focus'|'blur'|'focuschange'|'focusvisiblechange';
 
 typeFocusEvent={|
 target: Element|Document,
@@ -38,6 +40,21 @@ const targetEventTypes = [
 {name: 'blur',passive: true,capture: true},
 ];
 
+constrootEventTypes=[
+'keydown',
+'keypress',
+'keyup',
+'mousemove',
+'mousedown',
+'mouseup',
+'pointermove',
+'pointerdown',
+'pointerup',
+'touchmove',
+'touchstart',
+'touchend',
+];
+
 functioncreateFocusEvent(
 type: FocusEventType,
 target: Element|Document,
@@ -65,6 +82,13 @@ function dispatchFocusInEvents(
 constsyntheticEvent=createFocusEvent('focuschange',target);
 context.dispatchEvent(syntheticEvent,listener,{discrete: true});
 }
+if(props.onFocusVisibleChange&&state.isLocalFocusVisible){
+constlistener=()=>{
+props.onFocusVisibleChange(true);
+};
+constsyntheticEvent=createFocusEvent('focusvisiblechange',target);
+context.dispatchEvent(syntheticEvent,listener,{discrete: true});
+}
 }
 
 functiondispatchFocusOutEvents(
@@ -84,6 +108,23 @@ function dispatchFocusOutEvents(
 constsyntheticEvent=createFocusEvent('focuschange',target);
 context.dispatchEvent(syntheticEvent,listener,{discrete: true});
 }
+dispatchFocusVisibleOutEvent(context,props,state);
+}
+
+functiondispatchFocusVisibleOutEvent(
+context: ReactResponderContext,
+props: FocusProps,
+state: FocusState,
+){
+consttarget=((state.focusTarget: any): Element|Document);
+if(props.onFocusVisibleChange&&state.isLocalFocusVisible){
+constlistener=()=>{
+props.onFocusVisibleChange(false);
+};
+constsyntheticEvent=createFocusEvent('focusvisiblechange',target);
+context.dispatchEvent(syntheticEvent,listener,{discrete: true});
+state.isLocalFocusVisible=false;
+}
 }
 
 functionunmountResponder(
@@ -96,12 +137,16 @@ function unmountResponder(
 }
 }
 
+letisGlobalFocusVisible=true;
+
 constFocusResponder={
  targetEventTypes,
+ rootEventTypes,
 createInitialState(): FocusState{
 return{
-isFocused: false,
 focusTarget: null,
+isFocused: false,
+isLocalFocusVisible: false,
 };
 },
 stopLocalPropagation: true,
@@ -129,8 +174,9 @@ const FocusResponder = {
 // Browser focus is not expected to bubble.
 state.focusTarget=getEventCurrentTarget(event,context);
 if(state.focusTarget===target){
-dispatchFocusInEvents(context,props,state);
 state.isFocused=true;
+state.isLocalFocusVisible=isGlobalFocusVisible;
+dispatchFocusInEvents(context,props,state);
 }
 }
 break;
@@ -145,6 +191,59 @@ const FocusResponder = {
 }
 }
 },
+onRootEvent(
+event: ReactResponderEvent,
+context: ReactResponderContext,
+props: FocusProps,
+state: FocusState,
+): void{
+const{type,target}=event;
+
+switch(type){
+case 'mousemove':
+case 'mousedown':
+case 'mouseup':
+case 'pointermove':
+case 'pointerdown':
+case 'pointerup':
+case 'touchmove':
+case 'touchstart':
+case 'touchend': {
+// Ignore a Safari quirks where 'mousemove' is dispatched on the 'html'
+// element when the window blurs.
+if(type==='mousemove'&&target.nodeName==='HTML'){
+return;
+}
+
+isGlobalFocusVisible=false;
+
+// Focus should stop being visible if a pointer is used on the element
+// after it was focused using a keyboard.
+if(
+state.focusTarget===getEventCurrentTarget(event,context)&&
+(type==='mousedown'||
+type==='touchstart'||
+type==='pointerdown')
+){
+dispatchFocusVisibleOutEvent(context,props,state);
+}
+break;
+}
+
+case 'keydown':
+case 'keypress':
+case 'keyup': {
+constnativeEvent=event.nativeEvent;
+if(
+nativeEvent.key==='Tab'&&
+!(nativeEvent.metaKey||nativeEvent.altKey||nativeEvent.ctrlKey)
+){
+isGlobalFocusVisible=true;
+}
+break;
+}
+}
+},
 onUnmount(
 context: ReactResponderContext,
 props: FocusProps,

packages/react-events/src/__tests__/Focus-test.internal.js

@@ -20,6 +20,25 @@ const createFocusEvent = type => {
 returnevent;
 };
 
+constcreateKeyboardEvent=(type,data)=>{
+returnnewKeyboardEvent(type,{
+bubbles: true,
+cancelable: true,
+ ...data,
+});
+};
+
+constcreatePointerEvent=(type,data)=>{
+constevent=document.createEvent('CustomEvent');
+event.initCustomEvent(type,true,true);
+if(data!=null){
+Object.entries(data).forEach(([key,value])=>{
+event[key]=value;
+});
+}
+returnevent;
+};
+
 describe('Focus event responder',()=>{
 letcontainer;
 
@@ -138,6 +157,55 @@ describe('Focus event responder', () => {
 });
 });
 
+describe('onFocusVisibleChange',()=>{
+letonFocusVisibleChange,ref;
+
+beforeEach(()=>{
+onFocusVisibleChange=jest.fn();
+ref=React.createRef();
+constelement=(
+<FocusonFocusVisibleChange={onFocusVisibleChange}>
+<divref={ref}/>
+</Focus>
+);
+ReactDOM.render(element,container);
+});
+
+it('is called after "focus" and "blur" if keyboard navigation is active',()=>{
+// use keyboard first
+container.dispatchEvent(createKeyboardEvent('keydown',{key: 'Tab'}));
+ref.current.dispatchEvent(createFocusEvent('focus'));
+expect(onFocusVisibleChange).toHaveBeenCalledTimes(1);
+expect(onFocusVisibleChange).toHaveBeenCalledWith(true);
+ref.current.dispatchEvent(createFocusEvent('blur'));
+expect(onFocusVisibleChange).toHaveBeenCalledTimes(2);
+expect(onFocusVisibleChange).toHaveBeenCalledWith(false);
+});
+
+it('is called if non-keyboard event is dispatched on target previously focused with keyboard',()=>{
+// use keyboard first
+container.dispatchEvent(createKeyboardEvent('keydown',{key: 'Tab'}));
+ref.current.dispatchEvent(createFocusEvent('focus'));
+expect(onFocusVisibleChange).toHaveBeenCalledTimes(1);
+expect(onFocusVisibleChange).toHaveBeenCalledWith(true);
+// then use pointer on the target, focus should no longer be visible
+ref.current.dispatchEvent(createPointerEvent('pointerdown'));
+expect(onFocusVisibleChange).toHaveBeenCalledTimes(2);
+expect(onFocusVisibleChange).toHaveBeenCalledWith(false);
+// onFocusVisibleChange should not be called again
+ref.current.dispatchEvent(createFocusEvent('blur'));
+expect(onFocusVisibleChange).toHaveBeenCalledTimes(2);
+});
+
+it('is not called after "focus" and "blur" events without keyboard',()=>{
+ref.current.dispatchEvent(createPointerEvent('pointerdown'));
+ref.current.dispatchEvent(createFocusEvent('focus'));
+container.dispatchEvent(createPointerEvent('pointerdown'));
+ref.current.dispatchEvent(createFocusEvent('blur'));
+expect(onFocusVisibleChange).toHaveBeenCalledTimes(0);
+});
+});
+
 describe('nested Focus components',()=>{
 it('do not propagate events by default',()=>{
 constevents=[];

packages/react-events/src/__tests__/Press-test.internal.js

@@ -1090,10 +1090,10 @@ describe('Event responder: Press', () => {
 ref.current.dispatchEvent(
 createPointerEvent('pointermove',coordinatesInside),
 );
-ref.current.dispatchEvent(
+container.dispatchEvent(
 createPointerEvent('pointermove',coordinatesOutside),
 );
-ref.current.dispatchEvent(
+container.dispatchEvent(
 createPointerEvent('pointerup',coordinatesOutside),
 );
 jest.runAllTimers();
@@ -1135,13 +1135,13 @@ describe('Event responder: Press', () => {
 ref.current.dispatchEvent(
 createPointerEvent('pointermove',coordinatesInside),
 );
-ref.current.dispatchEvent(
+container.dispatchEvent(
 createPointerEvent('pointermove',coordinatesOutside),
 );
 jest.runAllTimers();
 expect(events).toEqual(['onPressMove']);
 events=[];
-ref.current.dispatchEvent(
+container.dispatchEvent(
 createPointerEvent('pointerup',coordinatesOutside),
 );
 jest.runAllTimers();