From 66623aa19540ab2ce30c5f7efba55d618ed85e76 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Fri, 3 Jan 2020 09:06:08 +0100 Subject: [PATCH 1/3] Small fixes per review --- packages/compose/README.md | 2 +- .../src/hooks/use-keyboard-shortcut/index.js | 17 ++++++++++++++--- .../editor/src/components/post-title/index.js | 2 +- .../keyboard-shortcuts/src/store/selectors.js | 17 ++++++++++------- 4 files changed, 26 insertions(+), 12 deletions(-) diff --git a/packages/compose/README.md b/packages/compose/README.md index 3dc619d4e7cb02..e6cbad5320a233 100644 --- a/packages/compose/README.md +++ b/packages/compose/README.md @@ -135,7 +135,7 @@ _Parameters_ - _shortcuts_ `(Array|string)`: Keyboard Shortcuts. - _callback_ `Function`: Shortcut callback. -- _options_ `Object`: Shortcut options. +- _options_ `WPKeyboarShortcutConfig`: Shortcut options. # **useMediaQuery** diff --git a/packages/compose/src/hooks/use-keyboard-shortcut/index.js b/packages/compose/src/hooks/use-keyboard-shortcut/index.js index f19a95bc9f3263..8e843b15d46d66 100644 --- a/packages/compose/src/hooks/use-keyboard-shortcut/index.js +++ b/packages/compose/src/hooks/use-keyboard-shortcut/index.js @@ -10,6 +10,17 @@ import { includes, castArray } from 'lodash'; */ import { useEffect } from '@wordpress/element'; +/** + * A block selection object. + * + * @typedef {Object} WPKeyboarShortcutConfig + * + * @property {boolean} [bindGlobal] Handle keyboard events anywhere including inside textarea/input fields. + * @property {string} [eventName] Event name used to trigger the handler, defaults to keydown. + * @property {boolean} [isDisabled] Disables the keyboard handler if the value is true. + * @property {Object} [target] React reference to the DOM element used to catch the keyboard event. + */ + /** * Return true if platform is MacOS. * @@ -27,9 +38,9 @@ function isAppleOS( _window = window ) { /** * Attach a keyboard shortcut handler. * - * @param {string[]|string} shortcuts Keyboard Shortcuts. - * @param {Function} callback Shortcut callback. - * @param {Object} options Shortcut options. + * @param {string[]|string} shortcuts Keyboard Shortcuts. + * @param {Function} callback Shortcut callback. + * @param {WPKeyboarShortcutConfig} options Shortcut options. */ function useKeyboardShortcut( shortcuts, callback, { bindGlobal = false, diff --git a/packages/editor/src/components/post-title/index.js b/packages/editor/src/components/post-title/index.js index d814a9dc07d24a..ac225c616f019a 100644 --- a/packages/editor/src/components/post-title/index.js +++ b/packages/editor/src/components/post-title/index.js @@ -111,7 +111,7 @@ class PostTitle extends Component { */ /* eslint-disable jsx-a11y/no-autofocus */ autoFocus={ document.body === document.activeElement && isCleanNewPost } - /* eslint-enable jsx-a11y/no-autofocus */ + /* eslint-enable jsx-a11y/no-autofocus */ /> { isSelected && isPostTypeViewable && } diff --git a/packages/keyboard-shortcuts/src/store/selectors.js b/packages/keyboard-shortcuts/src/store/selectors.js index 5979fe3ccdb488..2765f9f40022bc 100644 --- a/packages/keyboard-shortcuts/src/store/selectors.js +++ b/packages/keyboard-shortcuts/src/store/selectors.js @@ -19,6 +19,15 @@ import { displayShortcut, shortcutAriaLabel, rawShortcut } from '@wordpress/keyc */ const EMPTY_ARRAY = []; +/** + * {{[string]:Function}} Shortcut Formatting Methods. + */ +const FORMATTING_METHODS = { + display: displayShortcut, + raw: rawShortcut, + ariaLabel: shortcutAriaLabel, +}; + /** * Returns a string representing the key combination. * @@ -32,14 +41,8 @@ function getKeyCombinationRepresentation( shortcut, representation ) { return null; } - const formattingMethods = { - display: displayShortcut, - raw: rawShortcut, - ariaLabel: shortcutAriaLabel, - }; - return shortcut.modifier ? - formattingMethods[ representation ][ shortcut.modifier ]( shortcut.character ) : + FORMATTING_METHODS[ representation ][ shortcut.modifier ]( shortcut.character ) : shortcut.character; } From 89df7e374451d1f024c0457815aa5f31cb3904ce Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Fri, 3 Jan 2020 09:37:40 -0500 Subject: [PATCH 2/3] Keyboard Shortcuts: Improve typing detail --- .../data/data-core-keyboard-shortcuts.md | 2 +- .../keyboard-shortcuts/src/store/actions.js | 16 +++++++------ .../keyboard-shortcuts/src/store/selectors.js | 22 +++++++++++------ packages/keycodes/README.md | 12 ++++++---- packages/keycodes/src/index.js | 24 +++++++++++++++---- 5 files changed, 53 insertions(+), 23 deletions(-) diff --git a/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md b/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md index 8948bc387167fe..e125ddfab1ebf5 100644 --- a/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md +++ b/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md @@ -66,7 +66,7 @@ _Parameters_ - _state_ `Object`: Global state. - _name_ `string`: Shortcut name. -- _representation_ `string`: Type of reprensentation. (display, raw, ariaLabel ) +- _representation_ `null`: Type of representation (display, raw, ariaLabel). _Returns_ diff --git a/packages/keyboard-shortcuts/src/store/actions.js b/packages/keyboard-shortcuts/src/store/actions.js index a38c6c159c7420..e8e9678362b1af 100644 --- a/packages/keyboard-shortcuts/src/store/actions.js +++ b/packages/keyboard-shortcuts/src/store/actions.js @@ -1,10 +1,12 @@ +/** @typedef {import('@wordpress/keycodes').WPKeycodeModifier} WPKeycodeModifier */ + /** * Keyboard key combination. * * @typedef {Object} WPShortcutKeyCombination * - * @property {string} character Character. - * @property {string} [modifier] Modifier. + * @property {string} character Character. + * @property {WPKeycodeModifier|undefined} modifier Modifier. */ /** @@ -12,11 +14,11 @@ * * @typedef {Object} WPShortcutConfig * - * @property {string} name Shortcut name. - * @property {string} category Shortcut category. - * @property {string} description Shortcut description. - * @property {WPShortcutKeyCombination} keyCombination Shortcut key combination. - * @property {WPShortcutKeyCombination[]} [aliases] Shortcut aliases. + * @property {string} name Shortcut name. + * @property {string} category Shortcut category. + * @property {string} description Shortcut description. + * @property {WPShortcutKeyCombination} keyCombination Shortcut key combination. + * @property {WPShortcutKeyCombination[]} [aliases] Shortcut aliases. */ /** diff --git a/packages/keyboard-shortcuts/src/store/selectors.js b/packages/keyboard-shortcuts/src/store/selectors.js index 2765f9f40022bc..0b6216e9f5f348 100644 --- a/packages/keyboard-shortcuts/src/store/selectors.js +++ b/packages/keyboard-shortcuts/src/store/selectors.js @@ -11,16 +11,22 @@ import { displayShortcut, shortcutAriaLabel, rawShortcut } from '@wordpress/keyc /** @typedef {import('./actions').WPShortcutKeyCombination} WPShortcutKeyCombination */ +/** @typedef {import('@wordpress/keycodes').WPKeycodeHandlerByModifier} WPKeycodeHandlerByModifier */ + /** * Shared reference to an empty array for cases where it is important to avoid * returning a new array reference on every invocation. * - * @type {Array} + * @type {Array} */ const EMPTY_ARRAY = []; /** - * {{[string]:Function}} Shortcut Formatting Methods. + * Shortcut formatting methods. + * + * @property {WPKeycodeHandlerByModifier} display Display formatting. + * @property {WPKeycodeHandlerByModifier} rawShortcut Raw shortcut formatting. + * @property {WPKeycodeHandlerByModifier} ariaLabel ARIA label formatting. */ const FORMATTING_METHODS = { display: displayShortcut, @@ -31,8 +37,9 @@ const FORMATTING_METHODS = { /** * Returns a string representing the key combination. * - * @param {WPShortcutKeyCombination} shortcut Key combination. - * @param {string} representation Type of reprensentation. (display, raw, ariaLabel ) + * @param {?WPShortcutKeyCombination} shortcut Key combination. + * @param {keyof FORMATTING_METHODS} representation Type of representation + * (display, raw, ariaLabel). * * @return {string?} Shortcut representation. */ @@ -61,9 +68,10 @@ export function getShortcutKeyCombination( state, name ) { /** * Returns a string representing the main key combination for a given shortcut name. * - * @param {Object} state Global state. - * @param {string} name Shortcut name. - * @param {string} representation Type of reprensentation. (display, raw, ariaLabel ) + * @param {Object} state Global state. + * @param {string} name Shortcut name. + * @param {keyof FORMATTING_METHODS} representation Type of representation + * (display, raw, ariaLabel). * * @return {string?} Shortcut representation. */ diff --git a/packages/keycodes/README.md b/packages/keycodes/README.md index fb3a7440255fc3..7d54480a89b4bd 100644 --- a/packages/keycodes/README.md +++ b/packages/keycodes/README.md @@ -65,7 +65,7 @@ E.g. displayShortcut.primary( 'm' ) will return '⌘M' on Mac. _Type_ -- `Object` Keyed map of functions to display shortcuts. +- `WPKeycodeHandlerByModifier` Keyed map of functions to display shortcuts. # **displayShortcutList** @@ -74,7 +74,7 @@ E.g displayShortcutList.primary( 'm' ) will return [ '⌘', 'M' ] on Mac. _Type_ -- `Object` keyed map of functions to shortcut sequences +- `WPKeycodeHandlerByModifier` Keyed map of functions to shortcut sequences. # **DOWN** @@ -101,7 +101,7 @@ signals pressing ⌘M. _Type_ -- `Object` Keyed map of functions to match events. +- `WPKeycodeHandlerByModifier` Keyed map of functions to match events. # **LEFT** @@ -131,7 +131,7 @@ These are intended for user with the KeyboardShortcuts component or TinyMCE. _Type_ -- `Object` Keyed map of functions to raw shortcuts. +- `WPKeycodeHandlerByModifier` Keyed map of functions to raw shortcuts. # **RIGHT** @@ -146,6 +146,10 @@ Keycode for SHIFT key. An object that contains functions to return an aria label for a keyboard shortcut. E.g. shortcutAriaLabel.primary( '.' ) will return 'Command + Period' on Mac. +_Type_ + +- `WPKeycodeHandlerByModifier` Keyed map of functions to shortcut ARIA labels. + # **SPACE** Keycode for SPACE key. diff --git a/packages/keycodes/src/index.js b/packages/keycodes/src/index.js index ea0047a6596f45..3615ca06149316 100644 --- a/packages/keycodes/src/index.js +++ b/packages/keycodes/src/index.js @@ -24,6 +24,17 @@ import { __ } from '@wordpress/i18n'; */ import { isAppleOS } from './platform'; +/** + * @typedef {'primary'|'primaryShift'|'primaryAlt'|'secondary'|'access'|'ctrl'|'alt'|'ctrlShift'|'shift'|'shiftAlt'} WPKeycodeModifier + */ + +/** + * An object of handler functions for each of the possible modifier + * combinations. A handler will return a value for a given key. + * + * @typedef {{[M in WPKeycodeModifier]:(key:string)=>any}} WPKeycodeHandlerByModifier + */ + /** * Keycode for BACKSPACE key. */ @@ -118,7 +129,7 @@ export const modifiers = { * E.g. rawShortcut.primary( 'm' ) will return 'meta+m' on Mac. * These are intended for user with the KeyboardShortcuts component or TinyMCE. * - * @type {Object} Keyed map of functions to raw shortcuts. + * @type {WPKeycodeHandlerByModifier} Keyed map of functions to raw shortcuts. */ export const rawShortcut = mapValues( modifiers, ( modifier ) => { return ( character, _isApple = isAppleOS ) => { @@ -130,7 +141,8 @@ export const rawShortcut = mapValues( modifiers, ( modifier ) => { * Return an array of the parts of a keyboard shortcut chord for display * E.g displayShortcutList.primary( 'm' ) will return [ '⌘', 'M' ] on Mac. * - * @type {Object} keyed map of functions to shortcut sequences + * @type {WPKeycodeHandlerByModifier} Keyed map of functions to shortcut + * sequences. */ export const displayShortcutList = mapValues( modifiers, ( modifier ) => { return ( character, _isApple = isAppleOS ) => { @@ -161,7 +173,8 @@ export const displayShortcutList = mapValues( modifiers, ( modifier ) => { * An object that contains functions to display shortcuts. * E.g. displayShortcut.primary( 'm' ) will return '⌘M' on Mac. * - * @type {Object} Keyed map of functions to display shortcuts. + * @type {WPKeycodeHandlerByModifier} Keyed map of functions to display + * shortcuts. */ export const displayShortcut = mapValues( displayShortcutList, ( shortcutList ) => { return ( character, _isApple = isAppleOS ) => shortcutList( character, _isApple ).join( '' ); @@ -170,6 +183,9 @@ export const displayShortcut = mapValues( displayShortcutList, ( shortcutList ) /** * An object that contains functions to return an aria label for a keyboard shortcut. * E.g. shortcutAriaLabel.primary( '.' ) will return 'Command + Period' on Mac. + * + * @type {WPKeycodeHandlerByModifier} Keyed map of functions to shortcut ARIA + * labels. */ export const shortcutAriaLabel = mapValues( modifiers, ( modifier ) => { return ( character, _isApple = isAppleOS ) => { @@ -199,7 +215,7 @@ export const shortcutAriaLabel = mapValues( modifiers, ( modifier ) => { * E.g. isKeyboardEvent.primary( event, 'm' ) will return true if the event * signals pressing ⌘M. * - * @type {Object} Keyed map of functions to match events. + * @type {WPKeycodeHandlerByModifier} Keyed map of functions to match events. */ export const isKeyboardEvent = mapValues( modifiers, ( getModifiers ) => { return ( event, character, _isApple = isAppleOS ) => { From e8fd6619d2b6a1a92fd5a47c33ec04e4537408e4 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Fri, 3 Jan 2020 09:38:22 -0500 Subject: [PATCH 3/3] Compose: Fix typo WPKeyboardShortcutConfig --- packages/compose/README.md | 2 +- packages/compose/src/hooks/use-keyboard-shortcut/index.js | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/compose/README.md b/packages/compose/README.md index e6cbad5320a233..b473af456e8eca 100644 --- a/packages/compose/README.md +++ b/packages/compose/README.md @@ -135,7 +135,7 @@ _Parameters_ - _shortcuts_ `(Array|string)`: Keyboard Shortcuts. - _callback_ `Function`: Shortcut callback. -- _options_ `WPKeyboarShortcutConfig`: Shortcut options. +- _options_ `WPKeyboardShortcutConfig`: Shortcut options. # **useMediaQuery** diff --git a/packages/compose/src/hooks/use-keyboard-shortcut/index.js b/packages/compose/src/hooks/use-keyboard-shortcut/index.js index 8e843b15d46d66..d1004dba15a41b 100644 --- a/packages/compose/src/hooks/use-keyboard-shortcut/index.js +++ b/packages/compose/src/hooks/use-keyboard-shortcut/index.js @@ -13,7 +13,7 @@ import { useEffect } from '@wordpress/element'; /** * A block selection object. * - * @typedef {Object} WPKeyboarShortcutConfig + * @typedef {Object} WPKeyboardShortcutConfig * * @property {boolean} [bindGlobal] Handle keyboard events anywhere including inside textarea/input fields. * @property {string} [eventName] Event name used to trigger the handler, defaults to keydown. @@ -40,7 +40,7 @@ function isAppleOS( _window = window ) { * * @param {string[]|string} shortcuts Keyboard Shortcuts. * @param {Function} callback Shortcut callback. - * @param {WPKeyboarShortcutConfig} options Shortcut options. + * @param {WPKeyboardShortcutConfig} options Shortcut options. */ function useKeyboardShortcut( shortcuts, callback, { bindGlobal = false,