From 845ed0277a4158ffacb7409888c438b983f1e324 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ella=20van=C2=A0Durpe?= Date: Fri, 11 Dec 2020 16:31:34 +0200 Subject: [PATCH] Add typing observer docs --- .../src/components/observe-typing/index.js | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/packages/block-editor/src/components/observe-typing/index.js b/packages/block-editor/src/components/observe-typing/index.js index abd680d77409ef..3476d62c9692b6 100644 --- a/packages/block-editor/src/components/observe-typing/index.js +++ b/packages/block-editor/src/components/observe-typing/index.js @@ -15,6 +15,8 @@ import { TAB, } from '@wordpress/keycodes'; +/** @typedef {import('@wordpress/element').RefObject} RefObject */ + /** * Set of key codes upon which typing is to be initiated on a keydown event. * @@ -43,6 +45,12 @@ function isKeyDownEligibleForStartTyping( event ) { return ! shiftKey && KEY_DOWN_ELIGIBLE_KEY_CODES.has( keyCode ); } +/** + * Removes the `isTyping` flag when the mouse moves in the document of the given + * element. + * + * @param {RefObject} ref React ref containing an element. + */ export function useMouseMoveTypingReset( ref ) { const isTyping = useSelect( ( select ) => select( 'core/block-editor' ).isTyping() @@ -92,6 +100,15 @@ export function useMouseMoveTypingReset( ref ) { }, [ isTyping, stopTyping ] ); } +/** + * Sets and removes the `isTyping` flag based on user actions: + * + * - Sets the flag if the user types within the given element. + * - Removes the flag when the user selects some text, focusses a non-text + * field, presses ESC or TAB, or moves the mouse in the document. + * + * @param {RefObject} ref React ref containing an element. + */ export function useTypingObserver( ref ) { const isTyping = useSelect( ( select ) => select( 'core/block-editor' ).isTyping()