@wordpress/commands 1.39.1-next.v.202602091733.0 → 1.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/commands",
-	"version": "1.39.1-next.v.202602091733.0+daa0b19c4",
+	"version": "1.40.0",
 	"description": "Handles the commands menu.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -44,14 +44,15 @@
 	"react-native": "src/index",
 	"wpScript": true,
 	"dependencies": {
-		"@wordpress/base-styles": "^6.15.1-next.v.202602091733.0+daa0b19c4",
-		"@wordpress/components": "^32.2.1-next.v.202602091733.0+daa0b19c4",
-		"@wordpress/data": "^10.39.1-next.v.202602091733.0+daa0b19c4",
-		"@wordpress/element": "^6.39.1-next.v.202602091733.0+daa0b19c4",
-		"@wordpress/i18n": "^6.12.1-next.v.202602091733.0+daa0b19c4",
-		"@wordpress/icons": "^11.6.1-next.v.202602091733.0+daa0b19c4",
-		"@wordpress/keyboard-shortcuts": "^5.39.1-next.v.202602091733.0+daa0b19c4",
-		"@wordpress/private-apis": "^1.39.1-next.v.202602091733.0+daa0b19c4",
+		"@wordpress/base-styles": "^6.16.0",
+		"@wordpress/components": "^32.2.0",
+		"@wordpress/data": "^10.40.0",
+		"@wordpress/element": "^6.40.0",
+		"@wordpress/i18n": "^6.13.0",
+		"@wordpress/icons": "^11.7.0",
+		"@wordpress/keyboard-shortcuts": "^5.40.0",
+		"@wordpress/private-apis": "^1.40.0",
+		"@wordpress/warning": "^3.40.0",
 		"clsx": "^2.1.1",
 		"cmdk": "^1.0.0"
 	},
@@ -62,5 +63,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "74f59922b25e30904319373dda91bf8e81f3544e"
+	"gitHead": "376124aa10dbc2cc0c81c964ec00b99fcfee5382"
 }

package/src/components/command-menu.js

@@ -14,6 +14,8 @@ import {
 	useRef,
 	useCallback,
 	useMemo,
+	isValidElement,
+	Component,
 } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import {
@@ -26,7 +28,7 @@ import {
 	store as keyboardShortcutsStore,
 	useShortcut,
 } from '@wordpress/keyboard-shortcuts';
-import { Icon, search as inputIcon } from '@wordpress/icons';
+import { Icon, search as inputIcon, arrowRight } from '@wordpress/icons';
 
 /**
  * Internal dependencies
@@ -38,7 +40,54 @@ const { withIgnoreIMEEvents } = unlock( componentsPrivateApis );
 
 const inputLabel = __( 'Search commands and settings' );
 
-function CommandMenuLoader( { name, search, hook, setLoader, close } ) {
+/**
+ * Icons enforced per command category.
+ * Categories listed here will always use the specified icon,
+ * ignoring whatever icon the command itself provides.
+ */
+const CATEGORY_ICONS = {
+	view: arrowRight,
+};
+
+/**
+ * Translatable labels for command categories.
+ */
+const CATEGORY_LABELS = {
+	command: __( 'Command' ),
+	view: __( 'View' ),
+	edit: __( 'Edit' ),
+	action: __( 'Action' ),
+	workflow: __( 'Workflow' ),
+};
+
+/**
+ * Function that checks if the parameter is a valid icon.
+ * Taken from @wordpress/blocks/src/api/utils.js and copied
+ * in case requirements diverge and to avoid a dependency on @wordpress/blocks.
+ *
+ * @param {*} icon Parameter to be checked.
+ *
+ * @return {boolean} True if the parameter is a valid icon and false otherwise.
+ */
+
+export function isValidIcon( icon ) {
+	return (
+		!! icon &&
+		( typeof icon === 'string' ||
+			isValidElement( icon ) ||
+			typeof icon === 'function' ||
+			icon instanceof Component )
+	);
+}
+
+function CommandMenuLoader( {
+	name,
+	search,
+	hook,
+	setLoader,
+	close,
+	category,
+} ) {
 	const { isLoading, commands = [] } = hook( { search } ) ?? {};
 	useEffect( () => {
 		setLoader( name, isLoading );
@@ -50,35 +99,59 @@ function CommandMenuLoader( { name, search, hook, setLoader, close } ) {
 
 	return (
 		<>
-			{ commands.map( ( command ) => (
-				<Command.Item
-					key={ command.name }
-					value={ command.searchLabel ?? command.label }
-					keywords={ command.keywords }
-					onSelect={ () => command.callback( { close } ) }
-					id={ command.name }
-				>
-					<HStack
-						alignment="left"
-						className={ clsx( 'commands-command-menu__item', {
-							'has-icon': command.icon,
-						} ) }
+			{ commands.map( ( command ) => {
+				const commandCategory = command.category ?? category;
+				return (
+					<Command.Item
+						key={ command.name }
+						value={ command.searchLabel ?? command.label }
+						keywords={ command.keywords }
+						onSelect={ () => command.callback( { close } ) }
+						id={ command.name }
 					>
-						{ command.icon && <Icon icon={ command.icon } /> }
-						<span>
-							<TextHighlight
-								text={ command.label }
-								highlight={ search }
-							/>
-						</span>
-					</HStack>
-				</Command.Item>
-			) ) }
+						<HStack
+							alignment="left"
+							className={ clsx( 'commands-command-menu__item', {
+								'has-icon':
+									CATEGORY_ICONS[ commandCategory ] ||
+									command.icon,
+							} ) }
+						>
+							{ CATEGORY_ICONS[ commandCategory ] && (
+								<Icon
+									icon={ CATEGORY_ICONS[ commandCategory ] }
+								/>
+							) }
+							{ ! CATEGORY_ICONS[ commandCategory ] &&
+								isValidIcon( command.icon ) && (
+									<Icon icon={ command.icon } />
+								) }
+							<span className="commands-command-menu__item-label">
+								<TextHighlight
+									text={ command.label }
+									highlight={ search }
+								/>
+							</span>
+							{ CATEGORY_LABELS[ commandCategory ] && (
+								<span className="commands-command-menu__item-category">
+									{ CATEGORY_LABELS[ commandCategory ] }
+								</span>
+							) }
+						</HStack>
+					</Command.Item>
+				);
+			} ) }
 		</>
 	);
 }
 
-export function CommandMenuLoaderWrapper( { hook, search, setLoader, close } ) {
+export function CommandMenuLoaderWrapper( {
+	hook,
+	search,
+	setLoader,
+	close,
+	category,
+} ) {
 	// The "hook" prop is actually a custom React hook
 	// so to avoid breaking the rules of hooks
 	// the CommandMenuLoaderWrapper component need to be
@@ -100,6 +173,7 @@ export function CommandMenuLoaderWrapper( { hook, search, setLoader, close } ) {
 			search={ search }
 			setLoader={ setLoader }
 			close={ close }
+			category={ category }
 		/>
 	);
 }
@@ -133,16 +207,27 @@ export function CommandMenuGroup( { isContextual, search, setLoader, close } ) {
 					<HStack
 						alignment="left"
 						className={ clsx( 'commands-command-menu__item', {
-							'has-icon': command.icon,
+							'has-icon':
+								CATEGORY_ICONS[ command.category ] ||
+								command.icon,
 						} ) }
 					>
-						{ command.icon && <Icon icon={ command.icon } /> }
+						{ CATEGORY_ICONS[ command.category ] ? (
+							<Icon icon={ CATEGORY_ICONS[ command.category ] } />
+						) : (
+							command.icon && <Icon icon={ command.icon } />
+						) }
 						<span>
 							<TextHighlight
 								text={ command.label }
 								highlight={ search }
 							/>
 						</span>
+						{ CATEGORY_LABELS[ command.category ] && (
+							<span className="commands-command-menu__item-category">
+								{ CATEGORY_LABELS[ command.category ] }
+							</span>
+						) }
 					</HStack>
 				</Command.Item>
 			) ) }
@@ -153,6 +238,7 @@ export function CommandMenuGroup( { isContextual, search, setLoader, close } ) {
 					search={ search }
 					setLoader={ setLoader }
 					close={ close }
+					category={ loader.category }
 				/>
 			) ) }
 		</Command.Group>
@@ -212,7 +298,7 @@ export function CommandMenu() {
 
 	useShortcut(
 		'core/commands',
-		/** @type {import('react').KeyboardEventHandler} */
+		/** @type {React.KeyboardEventHandler} */
 		withIgnoreIMEEvents( ( event ) => {
 			// Bails to avoid obscuring the effect of the preceding handler(s).
 			if ( event.defaultPrevented ) {

package/src/components/style.scss

@@ -18,6 +18,7 @@
 	.components-modal__content {
 		margin: 0;
 		padding: 0;
+		overflow: hidden;
 	}
 }
 
@@ -29,6 +30,7 @@
 .commands-command-menu__header {
 	display: flex;
 	align-items: center;
+	gap: $grid-unit-10;
 	padding: 0 $grid-unit-20;
 
 	.components-button {
@@ -64,7 +66,7 @@
 		color: $gray-900;
 		margin: 0;
 		font-size: 15px;
-		line-height: 28px;
+		line-height: 24px;
 		border-radius: 0;
 
 		&::placeholder {
@@ -108,6 +110,7 @@
 			min-height: $button-size-next-default-40px;
 			padding: $grid-unit-05;
 			padding-left: $grid-unit-50; // Account for commands without icons.
+			padding-right: $grid-unit-20; // Accounts for the command category.
 		}
 
 		> .has-icon {
@@ -118,6 +121,19 @@
 	[cmdk-root] > [cmdk-list] {
 		max-height: $palette-max-height; // Specific to not have commands overflow oddly.
 		overflow: auto;
+		scroll-padding-top: $grid-unit-10;
+		scroll-padding-bottom: $grid-unit-10;
+
+		// Show border when there are commands or "nothing found" message.
+		&:has([cmdk-group-items]:not(:empty)),
+		&:has([cmdk-empty]) {
+			border-top: $border-width solid $gray-300;
+		}
+
+		// Only add vertical padding when there are commands to show.
+		&:has([cmdk-group-items]:not(:empty)) {
+			padding-top: $grid-unit-10;
+		}
 
 		// Ensures there is always padding bottom on the last group, when there are commands.
 		&
@@ -149,13 +165,29 @@
 	}
 }
 
-.commands-command-menu__item span {
+.commands-command-menu__item-label {
 	// Ensure commands do not run off the edge (great for post titles).
 	display: inline-block;
 	overflow: hidden;
 	text-overflow: ellipsis;
 	white-space: nowrap;
 	flex: 1;
+	min-width: 0;
+}
+
+.commands-command-menu__item-category {
+	flex: 0 0 auto;
+	margin-left: auto;
+	padding-left: $grid-unit-30;
+	color: $gray-700;
+	font-size: $default-font-size;
+	line-height: $default-line-height;
+	text-align: right;
+
+	[aria-selected="true"] &,
+	[cmdk-item]:active & {
+		color: rgba($white, 0.8);
+	}
 }
 
 .commands-command-menu__item mark {

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

@@ -54,6 +54,7 @@ import { store as commandsStore } from '../store';
  *                     ? record.title?.rendered
  *                     : __( '(no title)' ),
  *                 icon: page,
+ *                 category: 'edit',
  *                 callback: ( { close } ) => {
  *                     const args = {
  * 							p: '/page',
@@ -89,6 +90,7 @@ export default function useCommandLoader( loader ) {
 			name: loader.name,
 			hook: loader.hook,
 			context: loader.context,
+			category: loader.category,
 		} );
 		return () => {
 			unregisterCommandLoader( loader.name );
@@ -97,6 +99,7 @@ export default function useCommandLoader( loader ) {
 		loader.name,
 		loader.hook,
 		loader.context,
+		loader.category,
 		loader.disabled,
 		registerCommandLoader,
 		unregisterCommandLoader,

package/src/hooks/use-command.js

@@ -23,6 +23,7 @@ import { store as commandsStore } from '../store';
  *     name: 'myplugin/my-command-name',
  *     label: __( 'Add new post' ),
  *	   icon: plus,
+ *     category: 'command',
  *     callback: ({ close }) => {
  *         document.location.href = 'post-new.php';
  *         close();
@@ -44,6 +45,7 @@ export function useCommand( command ) {
 		registerCommand( {
 			name: command.name,
 			context: command.context,
+			category: command.category,
 			label: command.label,
 			searchLabel: command.searchLabel,
 			icon: command.icon,
@@ -59,6 +61,7 @@ export function useCommand( command ) {
 		command.searchLabel,
 		command.icon,
 		command.context,
+		command.category,
 		command.keywords,
 		command.disabled,
 		registerCommand,
@@ -81,6 +84,7 @@ export function useCommand( command ) {
  *         name: 'myplugin/add-post',
  *         label: __( 'Add new post' ),
  *         icon: plus,
+ *         category: 'command',
  *         callback: ({ close }) => {
  *             document.location.href = 'post-new.php';
  *             close();
@@ -90,6 +94,7 @@ export function useCommand( command ) {
  *         name: 'myplugin/edit-posts',
  *         label: __( 'Edit posts' ),
  *         icon: pencil,
+ *         category: 'view',
  *         callback: ({ close }) => {
  *             document.location.href = 'edit.php';
  *             close();
@@ -124,6 +129,7 @@ export function useCommands( commands ) {
 			registerCommand( {
 				name: command.name,
 				context: command.context,
+				category: command.category,
 				label: command.label,
 				searchLabel: command.searchLabel,
 				icon: command.icon,

package/src/store/actions.js

@@ -1,18 +1,37 @@
 /** @typedef {import('@wordpress/keycodes').WPKeycodeModifier} WPKeycodeModifier */
 
+/**
+ * @typedef {'command'|'view'|'edit'|'workflow'|'action'} WPCommandCategory
+ */
+
+/**
+ * Command categories allowed via registerCommand.
+ * The 'workflow' category is reserved for internal use
+ * and cannot be registered through this API.
+ *
+ * @type {Set<WPCommandCategory>}
+ */
+const REGISTERABLE_CATEGORIES = new Set( [
+	'command',
+	'view',
+	'edit',
+	'action',
+] );
+
 /**
  * Configuration of a registered keyboard shortcut.
  *
  * @typedef {Object} WPCommandConfig
  *
- * @property {string}      name        Command name.
- * @property {string}      label       Command label.
- * @property {string=}     searchLabel Command search label.
- * @property {string=}     context     Command context.
- * @property {JSX.Element} icon        Command icon.
- * @property {Function}    callback    Command callback.
- * @property {boolean}     disabled    Whether to disable the command.
- * @property {string[]=}   keywords    Command keywords for search matching.
+ * @property {string}             name        Command name.
+ * @property {string}             label       Command label.
+ * @property {string=}            searchLabel Command search label.
+ * @property {string=}            context     Command context.
+ * @property {WPCommandCategory=} category    Command category.
+ * @property {React.JSX.Element}  icon        Command icon.
+ * @property {Function}           callback    Command callback.
+ * @property {boolean}            disabled    Whether to disable the command.
+ * @property {string[]=}          keywords    Command keywords for search matching.
  */
 
 /**
@@ -26,6 +45,7 @@
  *
  * @property {string}              name     Command loader name.
  * @property {string=}             context  Command loader context.
+ * @property {WPCommandCategory=}  category Command loader category.
  * @property {WPCommandLoaderHook} hook     Command loader hook.
  * @property {boolean}             disabled Whether to disable the command loader.
  */
@@ -38,9 +58,17 @@
  * @return {Object} action.
  */
 export function registerCommand( config ) {
+	let { category } = config;
+
+	// Defaults to 'action' if no category is provided or if the category is invalid. Future versions will emit a warning.
+	if ( ! category || ! REGISTERABLE_CATEGORIES.has( category ) ) {
+		category = 'action';
+	}
+
 	return {
 		type: 'REGISTER_COMMAND',
 		...config,
+		category,
 	};
 }
 
@@ -66,9 +94,17 @@ export function unregisterCommand( name ) {
  * @return {Object} action.
  */
 export function registerCommandLoader( config ) {
+	let { category } = config;
+
+	// Defaults to 'action' if no category is provided or if the category is invalid. Future versions will emit a warning.
+	if ( ! category || ! REGISTERABLE_CATEGORIES.has( category ) ) {
+		category = 'action';
+	}
+
 	return {
 		type: 'REGISTER_COMMAND_LOADER',
 		...config,
+		category,
 	};
 }
 

package/src/store/reducer.js

@@ -21,6 +21,7 @@ function commands( state = {}, action ) {
 					label: action.label,
 					searchLabel: action.searchLabel,
 					context: action.context,
+					category: action.category,
 					callback: action.callback,
 					icon: action.icon,
 					keywords: action.keywords,
@@ -51,6 +52,7 @@ function commandLoaders( state = {}, action ) {
 				[ action.name ]: {
 					name: action.name,
 					context: action.context,
+					category: action.category,
 					hook: action.hook,
 				},
 			};