@wordpress/commands 0.2.0

package/src/components/command-menu.js

@@ -0,0 +1,216 @@
+/**
+ * External dependencies
+ */
+import { Command } from 'cmdk';
+
+/**
+ * WordPress dependencies
+ */
+import { useSelect, useDispatch } from '@wordpress/data';
+import { useState, useEffect, useRef, useCallback } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import { Modal, TextHighlight } from '@wordpress/components';
+import {
+	store as keyboardShortcutsStore,
+	useShortcut,
+} from '@wordpress/keyboard-shortcuts';
+
+/**
+ * Internal dependencies
+ */
+import { store as commandsStore } from '../store';
+
+function CommandMenuLoader( { name, search, hook, setLoader, close } ) {
+	const { isLoading, commands = [] } = hook( { search } ) ?? {};
+	useEffect( () => {
+		setLoader( name, isLoading );
+	}, [ setLoader, name, isLoading ] );
+
+	return (
+		<>
+			<Command.List>
+				{ isLoading && (
+					<Command.Loading>{ __( 'Searching…' ) }</Command.Loading>
+				) }
+
+				{ commands.map( ( command ) => (
+					<Command.Item
+						key={ command.name }
+						value={ command.name }
+						onSelect={ () => command.callback( { close } ) }
+					>
+						<span className="commands-command-menu__item">
+							<TextHighlight
+								text={ command.label }
+								highlight={ search }
+							/>
+						</span>
+					</Command.Item>
+				) ) }
+			</Command.List>
+		</>
+	);
+}
+
+export function CommandMenuLoaderWrapper( { hook, search, setLoader, close } ) {
+	// The "hook" prop is actually a custom React hook
+	// so to avoid breaking the rules of hooks
+	// the CommandMenuLoaderWrapper component need to be
+	// remounted on each hook prop change
+	// We use the key state to make sure we do that properly.
+	const currentLoader = useRef( hook );
+	const [ key, setKey ] = useState( 0 );
+	useEffect( () => {
+		if ( currentLoader.current !== hook ) {
+			currentLoader.current = hook;
+			setKey( ( prevKey ) => prevKey + 1 );
+		}
+	}, [ hook ] );
+
+	return (
+		<CommandMenuLoader
+			key={ key }
+			hook={ currentLoader.current }
+			search={ search }
+			setLoader={ setLoader }
+			close={ close }
+		/>
+	);
+}
+
+export function CommandMenuGroup( { group, search, setLoader, close } ) {
+	const { commands, loaders } = useSelect(
+		( select ) => {
+			const { getCommands, getCommandLoaders } = select( commandsStore );
+			return {
+				commands: getCommands( group ),
+				loaders: getCommandLoaders( group ),
+			};
+		},
+		[ group ]
+	);
+
+	return (
+		<Command.Group heading={ group }>
+			{ commands.map( ( command ) => (
+				<Command.Item
+					key={ command.name }
+					value={ command.name }
+					onSelect={ () => command.callback( { close } ) }
+				>
+					<span className="commands-command-menu__item">
+						<TextHighlight
+							text={ command.label }
+							highlight={ search }
+						/>
+					</span>
+				</Command.Item>
+			) ) }
+			{ loaders.map( ( loader ) => (
+				<CommandMenuLoaderWrapper
+					key={ loader.name }
+					hook={ loader.hook }
+					search={ search }
+					setLoader={ setLoader }
+					close={ close }
+				/>
+			) ) }
+		</Command.Group>
+	);
+}
+
+export function CommandMenu() {
+	const { registerShortcut } = useDispatch( keyboardShortcutsStore );
+	const [ search, setSearch ] = useState( '' );
+	const [ open, setOpen ] = useState( false );
+	const { groups } = useSelect( ( select ) => {
+		const { getGroups } = select( commandsStore );
+		return {
+			groups: getGroups(),
+		};
+	}, [] );
+	const [ loaders, setLoaders ] = useState( {} );
+
+	useEffect( () => {
+		registerShortcut( {
+			name: 'core/commands',
+			category: 'global',
+			description: __( 'Open the global command menu' ),
+			keyCombination: {
+				modifier: 'primary',
+				character: 'k',
+			},
+		} );
+	}, [ registerShortcut ] );
+
+	useShortcut(
+		'core/commands',
+		( event ) => {
+			event.preventDefault();
+			setOpen( ( prevOpen ) => ! prevOpen );
+		},
+		{
+			bindGlobal: true,
+		}
+	);
+
+	const setLoader = useCallback(
+		( name, value ) =>
+			setLoaders( ( current ) => ( {
+				...current,
+				[ name ]: value,
+			} ) ),
+		[]
+	);
+	const close = () => {
+		setSearch( '' );
+		setOpen( false );
+	};
+
+	if ( ! open ) {
+		return false;
+	}
+	const isLoading = Object.values( loaders ).some( Boolean );
+
+	return (
+		<Modal
+			className="commands-command-menu"
+			overlayClassName="commands-command-menu__overlay"
+			onRequestClose={ close }
+			__experimentalHideHeader
+		>
+			<div className="commands-command-menu__container">
+				<Command label={ __( 'Global Command Menu' ) }>
+					<div className="commands-command-menu__header">
+						<Command.Input
+							// The input should be focused when the modal is opened.
+							// eslint-disable-next-line jsx-a11y/no-autofocus
+							autoFocus
+							value={ search }
+							onValueChange={ setSearch }
+							placeholder={ __(
+								'Search for content and templates, or try commands like "Add…"'
+							) }
+						/>
+					</div>
+					<Command.List>
+						{ ! isLoading && (
+							<Command.Empty>
+								{ __( 'No results found.' ) }
+							</Command.Empty>
+						) }
+						{ groups.map( ( group ) => (
+							<CommandMenuGroup
+								key={ group }
+								group={ group }
+								search={ search }
+								setLoader={ setLoader }
+								close={ close }
+							/>
+						) ) }
+					</Command.List>
+				</Command>
+			</div>
+		</Modal>
+	);
+}

package/src/components/style.scss

@@ -0,0 +1,179 @@
+// dirty hack to clean up modal
+.commands-command-menu {
+	padding: 0;
+	width: 100%;
+	max-width: 680px;
+	position: relative;
+	top: 15%;
+
+	.components-modal__content {
+		margin: 0;
+		padding: 0;
+	}
+}
+
+.commands-command-menu__overlay {
+	display: block;
+	align-items: start;
+}
+
+.commands-command-menu__header {
+	display: flex;
+	align-items: center;
+	margin: $grid-unit-15 $grid-unit-15 0 $grid-unit-15;
+
+	.components-button {
+		height: $grid-unit-70;
+		width: $grid-unit-70;
+		border: 1px solid $gray-600;
+		border-right: 0;
+		justify-content: center;
+		border-radius: $radius-block-ui 0 0 $radius-block-ui;
+
+		& + [cmdk-input] {
+			border-top-left-radius: 0;
+			border-bottom-left-radius: 0;
+		}
+	}
+}
+
+.commands-command-menu__container {
+	[cmdk-linear-badge] {
+		height: 24px;
+		padding: 0 8px;
+		font-size: 12px;
+		color: $gray-800;
+		background: $gray-300;
+		border-radius: 4px;
+		width: fit-content;
+		display: flex;
+		align-items: center;
+		margin: $grid-unit-20 $grid-unit-20 0;
+	}
+
+	[cmdk-linear-shortcuts] {
+		display: flex;
+		margin-left: auto;
+		gap: $grid-unit-10;
+
+		kbd {
+			color: $gray-800;
+		}
+	}
+
+	[cmdk-input] {
+		border: 1px solid $gray-600;
+		width: 100%;
+		padding: $grid-unit-15 $grid-unit-20;
+		min-height: $grid-unit-70;
+		outline: none;
+		color: $gray-900;
+		margin: 0;
+		border-radius: $radius-block-ui;
+
+		&::placeholder {
+			color: $gray-600;
+		}
+
+		&:focus {
+			outline: 2px solid transparent;
+			border-color: var(--wp-admin-theme-color);
+			box-shadow: 0 0 0 1px var(--wp-admin-theme-color);
+		}
+	}
+
+	[cmdk-item] {
+		content-visibility: auto;
+		border-radius: $radius-block-ui;
+		cursor: pointer;
+		height: $grid-unit-50;
+		display: flex;
+		align-items: center;
+		gap: $grid-unit-15;
+		padding: 0 $grid-unit-20;
+		color: $gray-900;
+		user-select: none;
+		will-change: background, color;
+		transition: all 150ms ease;
+		transition-property: none;
+		position: relative;
+
+		&[aria-selected="true"] {
+			background: rgba(var(--wp-admin-theme-color--rgb), 0.04);
+			color: var(--wp-admin-theme-color);
+
+			svg {
+				color: var(--wp-admin-theme-color);
+			}
+		}
+
+		&[aria-disabled="true"] {
+			color: $gray-600;
+			cursor: not-allowed;
+		}
+
+		&:active {
+			transition-property: background;
+			background: rgba(var(--wp-admin-theme-color--rgb), 0.08);
+		}
+
+		& + [cmdk-item] {
+			margin-top: $grid-unit-05;
+		}
+
+		svg,
+		.dashicon {
+			width: $grid-unit-20;
+			height: $grid-unit-20;
+			color: $gray-800;
+		}
+	}
+
+	[cmdk-root] > [cmdk-list] {
+		min-height: 300px;
+		max-height: 400px;
+		overflow: auto;
+		overscroll-behavior: contain;
+		transition: 100ms ease;
+		transition-property: height;
+		margin: $grid-unit-15;
+	}
+
+	[cmdk-group-heading] {
+		user-select: none;
+		color: $gray-700;
+		padding: $grid-unit-30 $grid-unit-20 $grid-unit-20;
+		display: flex;
+		align-items: center;
+		font-size: 11px;
+		text-transform: uppercase;
+		font-weight: 500;
+		position: sticky;
+		top: 0;
+		background: $white;
+		z-index: 1;
+	}
+
+	[cmdk-empty] {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		height: $grid-unit-80;
+		white-space: pre-wrap;
+		color: $gray-800;
+	}
+
+	[cmdk-loading] {
+		padding: $grid-unit-20;
+	}
+
+	[cmdk-list-sizer] {
+		position: relative;
+	}
+}
+
+.commands-command-menu__item mark {
+	color: inherit;
+	background: unset;
+	font-weight: 600;
+}

package/src/hooks/use-command-loader.js

@@ -0,0 +1,30 @@
+/**
+ * WordPress dependencies
+ */
+import { useEffect } from '@wordpress/element';
+import { useDispatch } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { store as commandsStore } from '../store';
+
+/**
+ * Attach a command loader to the Global command menu.
+ *
+ * @param {import('../store/actions').WPCommandLoaderConfig} loader command loader config.
+ */
+export default function useCommandLoader( { name, group, hook } ) {
+	const { registerCommandLoader, unregisterCommandLoader } =
+		useDispatch( commandsStore );
+	useEffect( () => {
+		registerCommandLoader( {
+			name,
+			group,
+			hook,
+		} );
+		return () => {
+			unregisterCommandLoader( name, group );
+		};
+	}, [ name, group, hook, registerCommandLoader, unregisterCommandLoader ] );
+}

package/src/hooks/use-command.js

@@ -0,0 +1,41 @@
+/**
+ * WordPress dependencies
+ */
+import { useEffect, useRef } from '@wordpress/element';
+import { useDispatch } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { store as commandsStore } from '../store';
+
+/**
+ * Attach a command to the Global command menu.
+ *
+ * @param {import('../store/actions').WPCommandConfig} command command config.
+ */
+export default function useCommand( command ) {
+	const { registerCommand, unregisterCommand } = useDispatch( commandsStore );
+	const currentCallback = useRef( command.callback );
+	useEffect( () => {
+		currentCallback.current = command.callback;
+	}, [ command.callback ] );
+
+	useEffect( () => {
+		registerCommand( {
+			name: command.name,
+			group: command.group,
+			label: command.label,
+			callback: currentCallback.current,
+		} );
+		return () => {
+			unregisterCommand( command.name, command.group );
+		};
+	}, [
+		command.name,
+		command.label,
+		command.group,
+		registerCommand,
+		unregisterCommand,
+	] );
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { CommandMenu } from './components/command-menu';
+export { privateApis } from './private-apis';

package/src/private-apis.js

@@ -0,0 +1,22 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+/**
+ * Internal dependencies
+ */
+import { default as useCommand } from './hooks/use-command';
+import { default as useCommandLoader } from './hooks/use-command-loader';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
+		'@wordpress/commands'
+	);
+
+export const privateApis = {};
+lock( privateApis, {
+	useCommand,
+	useCommandLoader,
+} );

package/src/store/actions.js

@@ -0,0 +1,91 @@
+/** @typedef {import('@wordpress/keycodes').WPKeycodeModifier} WPKeycodeModifier */
+
+/**
+ * Configuration of a registered keyboard shortcut.
+ *
+ * @typedef {Object} WPCommandConfig
+ *
+ * @property {string}   name     Command name.
+ * @property {string}   label    Command label.
+ * @property {string=}  group    Command group.
+ * @property {Function} callback Command callback.
+ */
+
+/**
+ * @typedef {(search: string) => WPCommandConfig[]} WPCommandLoaderHook hoo
+ */
+
+/**
+ * Command loader config.
+ *
+ * @typedef {Object} WPCommandLoaderConfig
+ *
+ * @property {string}              name  Command loader name.
+ * @property {string=}             group Command loader group.
+ * @property {WPCommandLoaderHook} hook  Command loader hook.
+ */
+
+/**
+ * Returns an action object used to register a new command.
+ *
+ * @param {WPCommandConfig} config Command config.
+ *
+ * @return {Object} action.
+ */
+export function registerCommand( { name, label, callback, group = '' } ) {
+	return {
+		type: 'REGISTER_COMMAND',
+		name,
+		label,
+		callback,
+		group,
+	};
+}
+
+/**
+ * Returns an action object used to unregister a command.
+ *
+ * @param {string} name  Command name.
+ * @param {string} group Command group.
+ *
+ * @return {Object} action.
+ */
+export function unregisterCommand( name, group ) {
+	return {
+		type: 'UNREGISTER_COMMAND',
+		name,
+		group,
+	};
+}
+
+/**
+ * Register command loader.
+ *
+ * @param {WPCommandLoaderConfig} config Command loader config.
+ *
+ * @return {Object} action.
+ */
+export function registerCommandLoader( { name, group = '', hook } ) {
+	return {
+		type: 'REGISTER_COMMAND_LOADER',
+		name,
+		group,
+		hook,
+	};
+}
+
+/**
+ * Unregister command loader hook.
+ *
+ * @param {string} name  Command loader name.
+ * @param {string} group Command loader group.
+ *
+ * @return {Object} action.
+ */
+export function unregisterCommandLoader( name, group ) {
+	return {
+		type: 'UNREGISTER_COMMAND_LOADER',
+		name,
+		group,
+	};
+}

package/src/store/index.js

@@ -0,0 +1,28 @@
+/**
+ * WordPress dependencies
+ */
+import { createReduxStore, register } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import reducer from './reducer';
+import * as actions from './actions';
+import * as selectors from './selectors';
+
+const STORE_NAME = 'core/commands';
+
+/**
+ * Store definition for the commands namespace.
+ *
+ * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore
+ *
+ * @type {Object}
+ */
+export const store = createReduxStore( STORE_NAME, {
+	reducer,
+	actions,
+	selectors,
+} );
+
+register( store );

package/src/store/reducer.js

@@ -0,0 +1,81 @@
+/**
+ * WordPress dependencies
+ */
+import { combineReducers } from '@wordpress/data';
+
+/**
+ * Reducer returning the registered commands
+ *
+ * @param {Object} state  Current state.
+ * @param {Object} action Dispatched action.
+ *
+ * @return {Object} Updated state.
+ */
+function commands( state = {}, action ) {
+	switch ( action.type ) {
+		case 'REGISTER_COMMAND':
+			return {
+				...state,
+				[ action.group ]: {
+					...state[ action.group ],
+					[ action.name ]: {
+						name: action.name,
+						label: action.label,
+						group: action.group,
+						callback: action.callback,
+					},
+				},
+			};
+		case 'UNREGISTER_COMMAND': {
+			const { [ action.name ]: _, ...remainingState } =
+				state?.[ action.group ];
+			return {
+				...state,
+				[ action.group ]: remainingState,
+			};
+		}
+	}
+
+	return state;
+}
+
+/**
+ * Reducer returning the command loaders
+ *
+ * @param {Object} state  Current state.
+ * @param {Object} action Dispatched action.
+ *
+ * @return {Object} Updated state.
+ */
+function commandLoaders( state = {}, action ) {
+	switch ( action.type ) {
+		case 'REGISTER_COMMAND_LOADER':
+			return {
+				...state,
+				[ action.group ]: {
+					...state[ action.group ],
+					[ action.name ]: {
+						name: action.name,
+						hook: action.hook,
+					},
+				},
+			};
+		case 'UNREGISTER_COMMAND_LOADER': {
+			const { [ action.name ]: _, ...remainingState } =
+				state?.[ action.group ];
+			return {
+				...state,
+				[ action.group ]: remainingState,
+			};
+		}
+	}
+
+	return state;
+}
+
+const reducer = combineReducers( {
+	commands,
+	commandLoaders,
+} );
+
+export default reducer;