@wordpress/keyboard-shortcuts
Version:
Handling keyboard shortcuts.
360 lines (348 loc) • 11.9 kB
JavaScript
/**
* WordPress dependencies
*/
import { createSelector } from '@wordpress/data';
import { displayShortcut, shortcutAriaLabel, rawShortcut } from '@wordpress/keycodes';
/** @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<any>}
*/
const EMPTY_ARRAY = [];
/**
* 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,
raw: rawShortcut,
ariaLabel: shortcutAriaLabel
};
/**
* Returns a string representing the key combination.
*
* @param {?WPShortcutKeyCombination} shortcut Key combination.
* @param {keyof FORMATTING_METHODS} representation Type of representation
* (display, raw, ariaLabel).
*
* @return {?string} Shortcut representation.
*/
function getKeyCombinationRepresentation(shortcut, representation) {
if (!shortcut) {
return null;
}
return shortcut.modifier ? FORMATTING_METHODS[representation][shortcut.modifier](shortcut.character) : shortcut.character;
}
/**
* Returns the main key combination for a given shortcut name.
*
* @param {Object} state Global state.
* @param {string} name Shortcut name.
*
* @example
*
*```js
* import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
* import { useSelect } from '@wordpress/data';
* import { createInterpolateElement } from '@wordpress/element';
* import { sprintf } from '@wordpress/i18n';
* const ExampleComponent = () => {
* const {character, modifier} = useSelect(
* ( select ) =>
* select( keyboardShortcutsStore ).getShortcutKeyCombination(
* 'core/editor/next-region'
* ),
* []
* );
*
* return (
* <div>
* { createInterpolateElement(
* sprintf(
* 'Character: <code>%s</code> / Modifier: <code>%s</code>',
* character,
* modifier
* ),
* {
* code: <code />,
* }
* ) }
* </div>
* );
* };
*```
*
* @return {WPShortcutKeyCombination?} Key combination.
*/
export function getShortcutKeyCombination(state, name) {
return state[name] ? state[name].keyCombination : null;
}
/**
* Returns a string representing the main key combination for a given shortcut name.
*
* @param {Object} state Global state.
* @param {string} name Shortcut name.
* @param {keyof FORMATTING_METHODS} representation Type of representation
* (display, raw, ariaLabel).
* @example
*
*```js
* import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
* import { useSelect } from '@wordpress/data';
* import { sprintf } from '@wordpress/i18n';
*
* const ExampleComponent = () => {
* const {display, raw, ariaLabel} = useSelect(
* ( select ) =>{
* return {
* display: select( keyboardShortcutsStore ).getShortcutRepresentation('core/editor/next-region' ),
* raw: select( keyboardShortcutsStore ).getShortcutRepresentation('core/editor/next-region','raw' ),
* ariaLabel: select( keyboardShortcutsStore ).getShortcutRepresentation('core/editor/next-region', 'ariaLabel')
* }
* },
* []
* );
*
* return (
* <ul>
* <li>{ sprintf( 'display string: %s', display ) }</li>
* <li>{ sprintf( 'raw string: %s', raw ) }</li>
* <li>{ sprintf( 'ariaLabel string: %s', ariaLabel ) }</li>
* </ul>
* );
* };
*```
*
* @return {?string} Shortcut representation.
*/
export function getShortcutRepresentation(state, name, representation = 'display') {
const shortcut = getShortcutKeyCombination(state, name);
return getKeyCombinationRepresentation(shortcut, representation);
}
/**
* Returns the shortcut description given its name.
*
* @param {Object} state Global state.
* @param {string} name Shortcut name.
*
* @example
*
*```js
* import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
* import { useSelect } from '@wordpress/data';
* import { __ } from '@wordpress/i18n';
* const ExampleComponent = () => {
* const shortcutDescription = useSelect(
* ( select ) =>
* select( keyboardShortcutsStore ).getShortcutDescription( 'core/editor/next-region' ),
* []
* );
*
* return shortcutDescription ? (
* <div>{ shortcutDescription }</div>
* ) : (
* <div>{ __( 'No description.' ) }</div>
* );
* };
*```
* @return {?string} Shortcut description.
*/
export function getShortcutDescription(state, name) {
return state[name] ? state[name].description : null;
}
/**
* Returns the aliases for a given shortcut name.
*
* @param {Object} state Global state.
* @param {string} name Shortcut name.
* @example
*
*```js
* import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
* import { useSelect } from '@wordpress/data';
* import { createInterpolateElement } from '@wordpress/element';
* import { sprintf } from '@wordpress/i18n';
* const ExampleComponent = () => {
* const shortcutAliases = useSelect(
* ( select ) =>
* select( keyboardShortcutsStore ).getShortcutAliases(
* 'core/editor/next-region'
* ),
* []
* );
*
* return (
* shortcutAliases.length > 0 && (
* <ul>
* { shortcutAliases.map( ( { character, modifier }, index ) => (
* <li key={ index }>
* { createInterpolateElement(
* sprintf(
* 'Character: <code>%s</code> / Modifier: <code>%s</code>',
* character,
* modifier
* ),
* {
* code: <code />,
* }
* ) }
* </li>
* ) ) }
* </ul>
* )
* );
* };
*```
*
* @return {WPShortcutKeyCombination[]} Key combinations.
*/
export function getShortcutAliases(state, name) {
return state[name] && state[name].aliases ? state[name].aliases : EMPTY_ARRAY;
}
/**
* Returns the shortcuts that include aliases for a given shortcut name.
*
* @param {Object} state Global state.
* @param {string} name Shortcut name.
* @example
*
*```js
* import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
* import { useSelect } from '@wordpress/data';
* import { createInterpolateElement } from '@wordpress/element';
* import { sprintf } from '@wordpress/i18n';
*
* const ExampleComponent = () => {
* const allShortcutKeyCombinations = useSelect(
* ( select ) =>
* select( keyboardShortcutsStore ).getAllShortcutKeyCombinations(
* 'core/editor/next-region'
* ),
* []
* );
*
* return (
* allShortcutKeyCombinations.length > 0 && (
* <ul>
* { allShortcutKeyCombinations.map(
* ( { character, modifier }, index ) => (
* <li key={ index }>
* { createInterpolateElement(
* sprintf(
* 'Character: <code>%s</code> / Modifier: <code>%s</code>',
* character,
* modifier
* ),
* {
* code: <code />,
* }
* ) }
* </li>
* )
* ) }
* </ul>
* )
* );
* };
*```
*
* @return {WPShortcutKeyCombination[]} Key combinations.
*/
export const getAllShortcutKeyCombinations = createSelector((state, name) => {
return [getShortcutKeyCombination(state, name), ...getShortcutAliases(state, name)].filter(Boolean);
}, (state, name) => [state[name]]);
/**
* Returns the raw representation of all the keyboard combinations of a given shortcut name.
*
* @param {Object} state Global state.
* @param {string} name Shortcut name.
*
* @example
*
*```js
* import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
* import { useSelect } from '@wordpress/data';
* import { createInterpolateElement } from '@wordpress/element';
* import { sprintf } from '@wordpress/i18n';
*
* const ExampleComponent = () => {
* const allShortcutRawKeyCombinations = useSelect(
* ( select ) =>
* select( keyboardShortcutsStore ).getAllShortcutRawKeyCombinations(
* 'core/editor/next-region'
* ),
* []
* );
*
* return (
* allShortcutRawKeyCombinations.length > 0 && (
* <ul>
* { allShortcutRawKeyCombinations.map(
* ( shortcutRawKeyCombination, index ) => (
* <li key={ index }>
* { createInterpolateElement(
* sprintf(
* ' <code>%s</code>',
* shortcutRawKeyCombination
* ),
* {
* code: <code />,
* }
* ) }
* </li>
* )
* ) }
* </ul>
* )
* );
* };
*```
*
* @return {string[]} Shortcuts.
*/
export const getAllShortcutRawKeyCombinations = createSelector((state, name) => {
return getAllShortcutKeyCombinations(state, name).map(combination => getKeyCombinationRepresentation(combination, 'raw'));
}, (state, name) => [state[name]]);
/**
* Returns the shortcut names list for a given category name.
*
* @param {Object} state Global state.
* @param {string} name Category name.
* @example
*
*```js
* import { store as keyboardShortcutsStore } from '@wordpress/keyboard-shortcuts';
* import { useSelect } from '@wordpress/data';
*
* const ExampleComponent = () => {
* const categoryShortcuts = useSelect(
* ( select ) =>
* select( keyboardShortcutsStore ).getCategoryShortcuts(
* 'block'
* ),
* []
* );
*
* return (
* categoryShortcuts.length > 0 && (
* <ul>
* { categoryShortcuts.map( ( categoryShortcut ) => (
* <li key={ categoryShortcut }>{ categoryShortcut }</li>
* ) ) }
* </ul>
* )
* );
* };
*```
* @return {string[]} Shortcut names.
*/
export const getCategoryShortcuts = createSelector((state, categoryName) => {
return Object.entries(state).filter(([, shortcut]) => shortcut.category === categoryName).map(([name]) => name);
}, state => [state]);
//# sourceMappingURL=selectors.js.map