@wordpress/interface 4.0.1 → 4.1.3

package/build-style/style.css

@@ -122,6 +122,12 @@
   }
 }
 
+@media (min-width: 782px) {
+  .components-panel__header + .interface-complementary-area-header {
+    margin-top: 0;
+  }
+}
+
 .interface-complementary-area {
   background: #fff;
   color: #1e1e1e;
@@ -157,12 +163,18 @@
 .interface-complementary-area p {
   margin-top: 0;
 }
-.interface-complementary-area h2,
-.interface-complementary-area h3 {
+.interface-complementary-area h2 {
   font-size: 13px;
   color: #1e1e1e;
   margin-bottom: 1.5em;
 }
+.interface-complementary-area h3 {
+  font-size: 11px;
+  text-transform: uppercase;
+  font-weight: 500;
+  color: #1e1e1e;
+  margin-bottom: 1.5em;
+}
 .interface-complementary-area hr {
   border-top: none;
   border-bottom: 1px solid #f0f0f0;
@@ -383,6 +395,39 @@ body.is-fullscreen-mode .interface-interface-skeleton {
   bottom: 0;
 }
 
+.interface-more-menu-dropdown {
+  margin-left: -4px;
+}
+.interface-more-menu-dropdown .components-button {
+  width: auto;
+  padding: 0 2px;
+}
+@media (min-width: 600px) {
+  .interface-more-menu-dropdown {
+    margin-left: 0;
+  }
+  .interface-more-menu-dropdown .components-button {
+    padding: 0 4px;
+  }
+}
+
+.interface-more-menu-dropdown__content .components-popover__content {
+  min-width: 280px;
+}
+@media (min-width: 480px) {
+  .interface-more-menu-dropdown__content .components-popover__content {
+    width: auto;
+    max-width: 480px;
+  }
+}
+.interface-more-menu-dropdown__content .components-popover__content .components-dropdown-menu__menu {
+  padding: 0;
+}
+
+.components-popover.interface-more-menu-dropdown__content {
+  z-index: 99998;
+}
+
 .interface-pinned-items {
   display: flex;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/interface",
-	"version": "4.0.1",
+	"version": "4.1.3",
 	"description": "Interface module for WordPress. The package contains shared functionality across the modern JavaScript-based WordPress screens.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -32,20 +32,21 @@
 	],
 	"dependencies": {
 		"@babel/runtime": "^7.13.10",
-		"@wordpress/components": "^16.0.0",
-		"@wordpress/compose": "^5.0.1",
-		"@wordpress/data": "^6.0.1",
-		"@wordpress/deprecated": "^3.2.1",
-		"@wordpress/element": "^4.0.0",
-		"@wordpress/i18n": "^4.2.1",
-		"@wordpress/icons": "^5.0.1",
-		"@wordpress/plugins": "^4.0.1",
-		"@wordpress/viewport": "^4.0.1",
+		"@wordpress/a11y": "^3.2.3",
+		"@wordpress/components": "^19.0.1",
+		"@wordpress/compose": "^5.0.5",
+		"@wordpress/data": "^6.1.3",
+		"@wordpress/deprecated": "^3.2.2",
+		"@wordpress/element": "^4.0.3",
+		"@wordpress/i18n": "^4.2.3",
+		"@wordpress/icons": "^6.1.0",
+		"@wordpress/plugins": "^4.0.5",
+		"@wordpress/viewport": "^4.0.5",
 		"classnames": "^2.3.1",
 		"lodash": "^4.17.21"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "8b67fbd424bc67f81c2d825877f0fae726d6363a"
+	"gitHead": "393c2b5533837fd637e998d23f0124c081a10df0"
 }

package/src/components/complementary-area/style.scss

@@ -35,13 +35,21 @@
 		margin-top: 0;
 	}
 
-	h2,
-	h3 {
+	h2 {
 		font-size: $default-font-size;
 		color: $gray-900;
 		margin-bottom: 1.5em;
 	}
 
+	// Subheading style.
+	h3 {
+		font-size: 11px;
+		text-transform: uppercase;
+		font-weight: 500;
+		color: $gray-900;
+		margin-bottom: 1.5em;
+	}
+
 	hr {
 		border-top: none;
 		border-bottom: 1px solid $gray-100;

package/src/components/complementary-area-header/style.scss

@@ -31,3 +31,11 @@
 		}
 	}
 }
+
+// This overrides the negative margins between two consecutives panels.
+// since the first panel is hidden.
+.components-panel__header + .interface-complementary-area-header {
+	@include break-medium() {
+		margin-top: 0;
+	}
+}

package/src/components/index.js

@@ -3,4 +3,6 @@ export { default as ComplementaryAreaMoreMenuItem } from './complementary-area-m
 export { default as FullscreenMode } from './fullscreen-mode';
 export { default as InterfaceSkeleton } from './interface-skeleton';
 export { default as PinnedItems } from './pinned-items';
+export { default as MoreMenuDropdown } from './more-menu-dropdown';
+export { default as MoreMenuFeatureToggle } from './more-menu-feature-toggle';
 export { default as ActionItem } from './action-item';

package/src/components/interface-skeleton/index.js

@@ -9,7 +9,7 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { forwardRef, useEffect, useRef } from '@wordpress/element';
+import { forwardRef, useEffect } from '@wordpress/element';
 import { __unstableUseNavigateRegions as useNavigateRegions } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 import { useMergeRefs } from '@wordpress/compose';
@@ -44,8 +44,7 @@ function InterfaceSkeleton(
 	},
 	ref
 ) {
-	const fallbackRef = useRef();
-	const regionsClassName = useNavigateRegions( fallbackRef, shortcuts );
+	const navigateRegionsProps = useNavigateRegions( shortcuts );
 
 	useHTMLClass( 'interface-interface-skeleton__html-container' );
 
@@ -70,11 +69,12 @@ function InterfaceSkeleton(
 
 	return (
 		<div
-			ref={ useMergeRefs( [ ref, fallbackRef ] ) }
+			{ ...navigateRegionsProps }
+			ref={ useMergeRefs( [ ref, navigateRegionsProps.ref ] ) }
 			className={ classnames(
 				className,
 				'interface-interface-skeleton',
-				regionsClassName,
+				navigateRegionsProps.className,
 				!! footer && 'has-footer'
 			) }
 		>

package/src/components/more-menu-dropdown/README.md

@@ -0,0 +1,78 @@
+# MoreMenuDropdown
+
+`MoreMenuDropdown` is a convenient component for rendering an editor 'more' menu. This is typically a menu that provides:
+
+- menu items for quick toggling editor preferences.
+- a way to open dialogs for keyboard shortcuts and editor preferences.
+- links to help.
+
+This component implements a `DropdownMenu` component from the `@wordpress/components` package.
+
+See also the `MoreMenuFeatureToggle` component in the `@wordpress/interface` package, which provides an easy way to implement a feature toggle as a child of this component. Use with the `MenuGroup`, `MenuItem`, `MenuItemsChoice` components from the `@wordpress/components` package to implement more advanced behaviors.
+
+Note that just like the `DropdownMenu` component, this component accepts a render callback, which child elements should be returned from.
+
+## Example
+
+```jsx
+function MyEditorMenu() {
+	return (
+		<MoreMenuDropdown>
+			{ () => (
+				<MenuGroup label={ __( 'Features' ) }>
+					<MoreMenuFeatureToggle
+						scope="namespace/editor-or-plugin-name"
+						feature="myFeatureName"
+						label={ __( 'My feature' ) }
+						info={ __( 'A really awesome feature' ) }
+						messageActivated={ __( 'My feature activated' )}
+						messageDeactivated={ __( 'My feature deactivated' )}
+					/>
+				</MenuGroup>
+			) }
+		</MoreMenuDropdown>
+	);
+}
+```
+
+## Props
+
+### as
+
+Provide a component that the dropdown should render as. This may be useful if you need `MoreMenuDropdown` to render a `ToolbarDropdownMenu` instead of a `DropdownMenu`. Defaults to `DropdownMenu`.
+
+-   Type: `Component`
+-   Required: No.
+
+### className
+
+Provide an additional class name to the dropdown component.
+
+-   Type: `String`
+-   Required: No
+
+### label
+
+Change the label of the button that opens the dropdown.
+
+-   Default: 'Options'
+-   Type: `String`
+-   Required: No
+
+### popoverProps
+
+Override or extend the dropdown's popover props.
+
+See the documentation for the `DropdownMenu` and `Popover` components in the `@wordpress/components` package for more information.
+
+-   Type: `Object`
+-   Required: No
+
+### toggleProps
+
+Override or extend the dropdown's toggle props.
+
+See the documentation for the `DropdownMenu` and `Button` components in the `@wordpress/components` package for more information.
+
+-   Type: `Object`
+-   Required: No

package/src/components/more-menu-dropdown/index.js

@@ -0,0 +1,46 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { DropdownMenu } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+import { moreVertical } from '@wordpress/icons';
+
+export default function MoreMenuDropdown( {
+	as: DropdownComponent = DropdownMenu,
+	className,
+	/* translators: button label text should, if possible, be under 16 characters. */
+	label = __( 'Options' ),
+	popoverProps,
+	toggleProps,
+	children,
+} ) {
+	return (
+		<DropdownComponent
+			className={ classnames(
+				'interface-more-menu-dropdown',
+				className
+			) }
+			icon={ moreVertical }
+			label={ label }
+			popoverProps={ {
+				position: 'bottom left',
+				...popoverProps,
+				className: classnames(
+					'interface-more-menu-dropdown__content',
+					popoverProps?.className
+				),
+			} }
+			toggleProps={ {
+				tooltipPosition: 'bottom',
+				...toggleProps,
+			} }
+		>
+			{ ( onClose ) => children( onClose ) }
+		</DropdownComponent>
+	);
+}

package/src/components/more-menu-dropdown/style.scss

@@ -0,0 +1,35 @@
+.interface-more-menu-dropdown {
+	margin-left: -4px;
+
+	// the padding and margin of the more menu is intentionally non-standard
+	.components-button {
+		width: auto;
+		padding: 0 2px;
+	}
+
+	@include break-small() {
+		margin-left: 0;
+
+		.components-button {
+			padding: 0 4px;
+		}
+	}
+}
+
+.interface-more-menu-dropdown__content .components-popover__content {
+	min-width: 280px;
+
+	// Let the menu scale to fit items.
+	@include break-mobile() {
+		width: auto;
+		max-width: $break-mobile;
+	}
+
+	.components-dropdown-menu__menu {
+		padding: 0;
+	}
+}
+
+.components-popover.interface-more-menu-dropdown__content {
+	z-index: z-index(".components-popover.edit-widgets-more-menu__content");
+}

package/src/components/more-menu-feature-toggle/README.md

@@ -0,0 +1,59 @@
+# MoreMenuFeatureToggle
+
+`MoreMenuFeatureToggle` renders a menu item that can be used as a child of the `MoreMenuDropdown` component. The component
+is connected to the interface package's store, and will toggle the value of a 'feature' between true and false.
+
+This component implements a `MenuItem` component from the `@wordpress/components` package.
+
+## Props
+
+### scope
+
+The 'scope' of the feature. This is usually a namespaced string that represents the name of the editor (e.g. 'core/edit-post'), and often matches the name of the store for the editor.
+
+-   Type: `String`
+-   Required: Yes
+
+### feature
+
+The name of the feature to toggle (e.g. 'fixedToolbar').
+
+-   Type: `String`
+-   Required: Yes
+
+### label
+
+A human readable label for the feature.
+
+-   Type: `String`
+-   Required: Yes
+
+### info
+
+A human readable description of what this toggle does.
+
+-   Type: `Object`
+-   Required: No
+
+### messageActivated
+
+A message read by a screen reader when the feature is activated. (e.g. 'Fixed toolbar activated')
+
+-   Type: `String`
+-   Required: No
+
+### messageDeactivated
+
+A message read by a screen reader when the feature is deactivated. (e.g. 'Fixed toolbar deactivated')
+
+-   Type: `String`
+-   Required: No
+
+### shortcut
+
+A keyboard shortcut for the feature. This is just used for display purposes and the implementation of the shortcut should be handled separately.
+
+Consider using the `displayShortcut` helper from the `@wordpress/keycodes` package for this prop.
+
+-   Type: `Array`
+-   Required: No

package/src/components/more-menu-feature-toggle/index.js

@@ -0,0 +1,53 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect, useDispatch } from '@wordpress/data';
+import { MenuItem } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+import { check } from '@wordpress/icons';
+import { speak } from '@wordpress/a11y';
+
+/**
+ * Internal dependencies
+ */
+import { store as interfaceStore } from '../../store';
+
+export default function MoreMenuFeatureToggle( {
+	scope,
+	label,
+	info,
+	messageActivated,
+	messageDeactivated,
+	shortcut,
+	feature,
+} ) {
+	const isActive = useSelect(
+		( select ) =>
+			select( interfaceStore ).isFeatureActive( scope, feature ),
+		[ feature ]
+	);
+	const { toggleFeature } = useDispatch( interfaceStore );
+	const speakMessage = () => {
+		if ( isActive ) {
+			speak( messageDeactivated || __( 'Feature deactivated' ) );
+		} else {
+			speak( messageActivated || __( 'Feature activated' ) );
+		}
+	};
+
+	return (
+		<MenuItem
+			icon={ isActive && check }
+			isSelected={ isActive }
+			onClick={ () => {
+				toggleFeature( scope, feature );
+				speakMessage();
+			} }
+			role="menuitemcheckbox"
+			info={ info }
+			shortcut={ shortcut }
+		>
+			{ label }
+		</MenuItem>
+	);
+}

package/src/index.js

@@ -1,2 +1,2 @@
-export { store } from './store';
 export * from './components';
+export { store } from './store';

package/src/store/actions.js

@@ -82,3 +82,51 @@ export function pinItem( scope, itemId ) {
 export function unpinItem( scope, itemId ) {
 	return setMultipleEnableItem( 'pinnedItems', scope, itemId, false );
 }
+
+/**
+ * Returns an action object used in signalling that a feature should be toggled.
+ *
+ * @param {string} scope       The feature scope (e.g. core/edit-post).
+ * @param {string} featureName The feature name.
+ */
+export function toggleFeature( scope, featureName ) {
+	return function ( { select, dispatch } ) {
+		const currentValue = select.isFeatureActive( scope, featureName );
+		dispatch.setFeatureValue( scope, featureName, ! currentValue );
+	};
+}
+
+/**
+ * Returns an action object used in signalling that a feature should be set to
+ * a true or false value
+ *
+ * @param {string}  scope       The feature scope (e.g. core/edit-post).
+ * @param {string}  featureName The feature name.
+ * @param {boolean} value       The value to set.
+ *
+ * @return {Object} Action object.
+ */
+export function setFeatureValue( scope, featureName, value ) {
+	return {
+		type: 'SET_FEATURE_VALUE',
+		scope,
+		featureName,
+		value: !! value,
+	};
+}
+
+/**
+ * Returns an action object used in signalling that defaults should be set for features.
+ *
+ * @param {string}                  scope    The feature scope (e.g. core/edit-post).
+ * @param {Object<string, boolean>} defaults A key/value map of feature names to values.
+ *
+ * @return {Object} Action object.
+ */
+export function setFeatureDefaults( scope, defaults ) {
+	return {
+		type: 'SET_FEATURE_DEFAULTS',
+		scope,
+		defaults,
+	};
+}

package/src/store/index.js

@@ -22,7 +22,8 @@ export const store = createReduxStore( STORE_NAME, {
 	reducer,
 	actions,
 	selectors,
-	persist: [ 'enableItems' ],
+	persist: [ 'enableItems', 'preferences' ],
+	__experimentalUseThunks: true,
 } );
 
 // Once we build a more generic persistence plugin that works across types of stores
@@ -31,5 +32,6 @@ registerStore( STORE_NAME, {
 	reducer,
 	actions,
 	selectors,
-	persist: [ 'enableItems' ],
+	persist: [ 'enableItems', 'preferences' ],
+	__experimentalUseThunks: true,
 } );

package/src/store/reducer.js

@@ -78,6 +78,59 @@ export function multipleEnableItems(
 	};
 }
 
+/**
+ * Reducer returning the defaults for user preferences.
+ *
+ * This is kept intentionally separate from the preferences
+ * themselves so that defaults are not persisted.
+ *
+ * @param {Object} state  Current state.
+ * @param {Object} action Dispatched action.
+ *
+ * @return {Object} Updated state.
+ */
+export const preferenceDefaults = combineReducers( {
+	features( state = {}, action ) {
+		if ( action.type === 'SET_FEATURE_DEFAULTS' ) {
+			const { scope, defaults } = action;
+			return {
+				...state,
+				[ scope ]: {
+					...state[ scope ],
+					...defaults,
+				},
+			};
+		}
+
+		return state;
+	},
+} );
+
+/**
+ * Reducer returning the user preferences.
+ *
+ * @param {Object} state  Current state.
+ * @param {Object} action Dispatched action.
+ *
+ * @return {Object} Updated state.
+ */
+export const preferences = combineReducers( {
+	features( state = {}, action ) {
+		if ( action.type === 'SET_FEATURE_VALUE' ) {
+			const { scope, featureName, value } = action;
+			return {
+				...state,
+				[ scope ]: {
+					...state[ scope ],
+					[ featureName ]: value,
+				},
+			};
+		}
+
+		return state;
+	},
+} );
+
 const enableItems = combineReducers( {
 	singleEnableItems,
 	multipleEnableItems,
@@ -85,4 +138,6 @@ const enableItems = combineReducers( {
 
 export default combineReducers( {
 	enableItems,
+	preferenceDefaults,
+	preferences,
 } );

package/src/store/selectors.js

@@ -61,3 +61,23 @@ export function isItemPinned( state, scope, item ) {
 		false
 	);
 }
+
+/**
+ * Returns a boolean indicating whether a feature is active for a particular
+ * scope.
+ *
+ * @param {Object} state       The store state.
+ * @param {string} scope       The scope of the feature (e.g. core/edit-post).
+ * @param {string} featureName The name of the feature.
+ *
+ * @return {boolean} Is the feature enabled?
+ */
+export function isFeatureActive( state, scope, featureName ) {
+	const featureValue = state.preferences.features[ scope ]?.[ featureName ];
+	const defaultedFeatureValue =
+		featureValue !== undefined
+			? featureValue
+			: state.preferenceDefaults.features[ scope ]?.[ featureName ];
+
+	return !! defaultedFeatureValue;
+}