Add new @wordpress/preferences package

package.json

@@ -65,6 +65,7 @@
 		"@wordpress/notices": "file:packages/notices",
 		"@wordpress/nux": "file:packages/nux",
 		"@wordpress/plugins": "file:packages/plugins",
+		"@wordpress/preferences": "file:packages/preferences",
 		"@wordpress/primitives": "file:packages/primitives",
 		"@wordpress/priority-queue": "file:packages/priority-queue",
 		"@wordpress/react-i18n": "file:packages/react-i18n",

packages/base-styles/_z-index.scss

@@ -156,6 +156,7 @@ $z-layers: (
 	".components-popover.edit-post-more-menu__content": 99998,
 	".components-popover.edit-site-more-menu__content": 99998,
 	".components-popover.edit-widgets-more-menu__content": 99998,
+	".components-popover.preferences-more-menu__content": 99998,
 	".components-popover.block-editor-rich-text__inline-format-toolbar": 99998,
 	".components-popover.block-editor-warning__dropdown": 99998,
 	".components-popover.edit-navigation-menu-actions__switcher-dropdown": 99998,

packages/preferences/.npmrc

@@ -0,0 +1 @@
+package-lock=false

packages/preferences/CHANGELOG.md

@@ -0,0 +1,7 @@
+<!-- Learn how to maintain this file at https://github.com/WordPress/gutenberg/tree/HEAD/packages#maintaining-changelogs. -->
+
+## Unreleased
+
+## 1.0.0
+
+-   Initial version of the package.

packages/preferences/README.md

@@ -0,0 +1,174 @@
+# Preferences
+
+Utilities for storing WordPress preferences.
+
+## Installation
+
+Install the module
+
+```bash
+npm install @wordpress/preferences --save
+```
+
+_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._
+
+## Examples
+
+### Data store
+
+Preferences are persisted values of any kind.
+
+Set the default preferences for any features on initialization by dispatching an action:
+
+```js
+import { dispatch } from '@wordpress/data';
+import { store as preferencesStore } from '@wordpress/preferences';
+
+function initialize() {
+	// ...
+
+	dispatch( preferencesStore ).setDefaults(
+		'namespace/editor-or-plugin-name',
+		{
+			myBooleanFeature: true,
+		}
+	);
+
+	// ...
+}
+```
+
+Or the `get` selector to get a preference value, and the `set` action to update a preference to any value:
+
+```js
+wp.data
+	.select( 'core/preferences' )
+	.get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // 1
+wp.data
+	.dispatch( 'core/preferences' )
+	.set( 'namespace/editor-or-plugin-name', 'myPreferenceName', 2 );
+wp.data
+	.select( 'core/preferences' )
+	.get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // 2
+```
+
+Use the `toggle` action to flip a boolean preference between `true` and `false`:
+
+```js
+wp.data
+	.select( 'core/preferences' )
+	.get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // true
+wp.data
+	.dispatch( 'core/preferences' )
+	.toggle( 'namespace/editor-or-plugin-name', 'myPreferenceName' );
+wp.data
+	.select( 'core/preferences' )
+	.get( 'namespace/editor-or-plugin-name', 'myPreferenceName' ); // false
+```
+
+### Components
+
+The `PreferenceToggleMenuItem` components can be used with a `DropdownMenu` to implement a menu for changing preferences.
+
+Also see the `MoreMenuDropdown` component from the `@wordpress/interface` package for implementing a more menu.
+
+```jsx
+function MyEditorMenu() {
+	return (
+		<MoreMenuDropdown>
+			{ () => (
+				<MenuGroup label={ __( 'Features' ) }>
+					<PreferenceToggleMenuItem
+						scope="namespace/editor-or-plugin-name"
+						name="myPreferenceName"
+						label={ __( 'My feature' ) }
+						info={ __( 'A really awesome feature' ) }
+						messageActivated={ __( 'My feature activated' ) }
+						messageDeactivated={ __( 'My feature deactivated' ) }
+					/>
+				</MenuGroup>
+			) }
+		</MoreMenuDropdown>
+	);
+}
+```
+
+## API Reference
+
+### Actions
+
+The following set of dispatching action creators are available on the object returned by `wp.data.dispatch( 'core/preferences' )`:
+
+<!-- START TOKEN(Autogenerated actions|src/store/actions.js) -->
+
+#### set
+
+Returns an action object used in signalling that a preference should be set
+to a value
+
+_Parameters_
+
+-   _scope_ `string`: The preference scope (e.g. core/edit-post).
+-   _name_ `string`: The preference name.
+-   _value_ `*`: The value to set.
+
+_Returns_
+
+-   `Object`: Action object.
+
+#### setDefaults
+
+Returns an action object used in signalling that preference defaults should
+be set.
+
+_Parameters_
+
+-   _scope_ `string`: The preference scope (e.g. core/edit-post).
+-   _defaults_ `Object<string, *>`: A key/value map of preference names to values.
+
+_Returns_
+
+-   `Object`: Action object.
+
+#### toggle
+
+Returns an action object used in signalling that a preference should be
+toggled.
+
+_Parameters_
+
+-   _scope_ `string`: The preference scope (e.g. core/edit-post).
+-   _name_ `string`: The preference name.
+
+<!-- END TOKEN(Autogenerated actions|src/store/actions.js) -->
+
+### Selectors
+
+The following selectors are available on the object returned by `wp.data.select( 'core/preferences' )`:
+
+<!-- START TOKEN(Autogenerated selectors|src/store/selectors.js) -->
+
+#### get
+
+Returns a boolean indicating whether a prefer is active for a particular
+scope.
+
+_Parameters_
+
+-   _state_ `Object`: The store state.
+-   _scope_ `string`: The scope of the feature (e.g. core/edit-post).
+-   _name_ `string`: The name of the feature.
+
+_Returns_
+
+-   `*`: Is the feature enabled?
+
+<!-- END TOKEN(Autogenerated selectors|src/store/selectors.js) -->
+
+## Contributing to this package
+
+This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
+
+To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).
+
+<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/preferences/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@wordpress/preferences",
+	"version": "1.0.0-prerelease",
+	"private": true,
+	"description": "Utilities for managing WordPress preferences.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"preferences",
+		"settings",
+		"options"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/preferences/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/preferences"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"engines": {
+		"node": ">=12"
+	},
+	"main": "build/index.js",
+	"module": "build-module/index.js",
+	"react-native": "src/index",
+	"types": "build-types",
+	"sideEffects": false,
+	"dependencies": {
+		"@babel/runtime": "^7.16.0",
+		"@wordpress/a11y": "file:../a11y",
+		"@wordpress/components": "file:../components",
+		"@wordpress/data": "file:../data",
+		"@wordpress/i18n": "file:../i18n",
+		"@wordpress/icons": "file:../icons",
+		"classnames": "^2.3.1"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

packages/preferences/src/components/index.js

@@ -0,0 +1 @@
+export { default as PreferenceToggleMenuItem } from './preference-toggle-menu-item';

packages/preferences/src/components/preference-toggle-menu-item/README.md

@@ -0,0 +1,58 @@
+# PreferenceToggleMenuItem
+
+`PreferenceToggleMenuItem` renders a menu item that is connected to the preference package's store, and will toggle the value of a 'preference' 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
+
+### name
+
+The name of the preference 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

packages/preferences/src/components/preference-toggle-menu-item/index.js

@@ -0,0 +1,66 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect, useDispatch } from '@wordpress/data';
+import { MenuItem } from '@wordpress/components';
+import { __, sprintf } from '@wordpress/i18n';
+import { check } from '@wordpress/icons';
+import { speak } from '@wordpress/a11y';
+
+/**
+ * Internal dependencies
+ */
+import { store as preferencesStore } from '../../store';
+
+export default function PreferenceToggleMenuItem( {
+	scope,
+	name,
+	label,
+	info,
+	messageActivated,
+	messageDeactivated,
+	shortcut,
+} ) {
+	const isActive = useSelect(
+		( select ) => !! select( preferencesStore ).get( scope, name ),
+		[ name ]
+	);
+	const { toggle } = useDispatch( preferencesStore );
+	const speakMessage = () => {
+		if ( isActive ) {
+			const message =
+				messageDeactivated ||
+				sprintf(
+					/* translators: %s: preference name, e.g. 'Fullscreen mode' */
+					__( 'Preference deactivated - %s' ),
+					label
+				);
+			speak( message );
+		} else {
+			const message =
+				messageActivated ||
+				sprintf(
+					/* translators: %s: preference name, e.g. 'Fullscreen mode' */
+					__( 'Preference activated - %s' ),
+					label
+				);
+			speak( message );
+		}
+	};
+
+	return (
+		<MenuItem
+			icon={ isActive && check }
+			isSelected={ isActive }
+			onClick={ () => {
+				toggle( scope, name );
+				speakMessage();
+			} }
+			role="menuitemcheckbox"
+			info={ info }
+			shortcut={ shortcut }
+		>
+			{ label }
+		</MenuItem>
+	);
+}

packages/preferences/src/index.js

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