@wordpress/preferences 3.26.0 → 3.28.0

package/build-style/style.css

@@ -0,0 +1,199 @@
+/**
+*  Converts a hex value into the rgb equivalent.
+*
+* @param {string} hex - the hexadecimal value to convert
+* @return {string} comma separated rgb values
+*/
+/**
+ * Colors
+ */
+/**
+ * Breakpoints & Media Queries
+ */
+/**
+ * SCSS Variables.
+ *
+ * Please use variables from this sheet to ensure consistency across the UI.
+ * Don't add to this sheet unless you're pretty sure the value will be reused in many places.
+ * For example, don't add rules to this sheet that affect block visuals. It's purely for UI.
+ */
+/**
+*  Converts a hex value into the rgb equivalent.
+*
+* @param {string} hex - the hexadecimal value to convert
+* @return {string} comma separated rgb values
+*/
+/**
+ * Colors
+ */
+/**
+ * Fonts & basic variables.
+ */
+/**
+ * Grid System.
+ * https://make.wordpress.org/design/2019/10/31/proposal-a-consistent-spacing-system-for-wordpress/
+ */
+/**
+ * Dimensions.
+ */
+/**
+ * Shadows.
+ */
+/**
+ * Editor widths.
+ */
+/**
+ * Block & Editor UI.
+ */
+/**
+ * Block paddings.
+ */
+/**
+ * React Native specific.
+ * These variables do not appear to be used anywhere else.
+ */
+/**
+*  Converts a hex value into the rgb equivalent.
+*
+* @param {string} hex - the hexadecimal value to convert
+* @return {string} comma separated rgb values
+*/
+/**
+ * Long content fade mixin
+ *
+ * Creates a fading overlay to signify that the content is longer
+ * than the space allows.
+ */
+/**
+ * Breakpoint mixins
+ */
+/**
+ * Focus styles.
+ */
+/**
+ * Applies editor left position to the selector passed as argument
+ */
+/**
+ * Styles that are reused verbatim in a few places
+ */
+/**
+ * Allows users to opt-out of animations via OS-level preferences.
+ */
+/**
+ * Reset default styles for JavaScript UI based pages.
+ * This is a WP-admin agnostic reset
+ */
+/**
+ * Reset the WP Admin page styles for Gutenberg-like pages.
+ */
+:root {
+  --wp-admin-theme-color: #007cba;
+  --wp-admin-theme-color--rgb: 0, 124, 186;
+  --wp-admin-theme-color-darker-10: #006ba1;
+  --wp-admin-theme-color-darker-10--rgb: 0, 107, 161;
+  --wp-admin-theme-color-darker-20: #005a87;
+  --wp-admin-theme-color-darker-20--rgb: 0, 90, 135;
+  --wp-admin-border-width-focus: 2px;
+  --wp-block-synced-color: #7a00df;
+  --wp-block-synced-color--rgb: 122, 0, 223;
+}
+@media (min-resolution: 192dpi) {
+  :root {
+    --wp-admin-border-width-focus: 1.5px;
+  }
+}
+
+.preference-base-option + .preference-base-option {
+  margin-top: 16px;
+}
+.preference-base-option .components-base-control__help {
+  margin-top: 0;
+  margin-left: 48px;
+}
+
+@media (min-width: 600px) {
+  .preferences-modal {
+    width: calc(100% - 32px);
+    height: calc(100% - 120px);
+  }
+}
+@media (min-width: 782px) {
+  .preferences-modal {
+    width: 750px;
+  }
+}
+@media (min-width: 960px) {
+  .preferences-modal {
+    height: 70%;
+  }
+}
+@media (max-width: 781px) {
+  .preferences-modal .components-modal__content {
+    padding: 0;
+  }
+}
+
+.preferences__tabs-tablist {
+  position: absolute;
+  top: 84px;
+  left: 16px;
+  width: 160px;
+}
+
+.preferences__tabs-tab {
+  border-radius: 2px;
+  font-weight: 400;
+}
+.preferences__tabs-tab[aria-selected=true] {
+  background: #f0f0f0;
+  box-shadow: none;
+  font-weight: 500;
+}
+.preferences__tabs-tab[aria-selected=true]::after {
+  content: none;
+}
+.preferences__tabs-tab[role=tab]:focus:not(:disabled) {
+  box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color);
+  outline: 2px solid transparent;
+}
+.preferences__tabs-tab:focus-visible::before {
+  content: none;
+}
+
+.preferences__tabs-tabpanel {
+  padding-left: 24px;
+  margin-left: 160px;
+}
+
+@media (max-width: 781px) {
+  .preferences__provider {
+    height: 100%;
+  }
+}
+.preferences-modal__section {
+  margin: 0 0 2.5rem 0;
+}
+.preferences-modal__section:last-child {
+  margin: 0;
+}
+
+.preferences-modal__section-legend {
+  margin-bottom: 8px;
+}
+
+.preferences-modal__section-title {
+  font-size: 0.9rem;
+  font-weight: 600;
+  margin-top: 0;
+}
+
+.preferences-modal__section-description {
+  margin: -8px 0 8px 0;
+  font-size: 12px;
+  font-style: normal;
+  color: #757575;
+}
+
+.preferences-modal__section:has(.preferences-modal__section-content:empty) {
+  display: none;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/preferences",
-	"version": "3.26.0",
+	"version": "3.28.0",
 	"description": "Utilities for managing WordPress preferences.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -29,12 +29,15 @@
 	"sideEffects": false,
 	"dependencies": {
 		"@babel/runtime": "^7.16.0",
-		"@wordpress/a11y": "^3.49.0",
-		"@wordpress/components": "^25.15.0",
-		"@wordpress/data": "^9.19.0",
-		"@wordpress/element": "^5.26.0",
-		"@wordpress/i18n": "^4.49.0",
-		"@wordpress/icons": "^9.40.0",
+		"@wordpress/a11y": "^3.51.0",
+		"@wordpress/components": "^26.0.0",
+		"@wordpress/compose": "^6.28.0",
+		"@wordpress/data": "^9.21.0",
+		"@wordpress/deprecated": "^3.51.0",
+		"@wordpress/element": "^5.28.0",
+		"@wordpress/i18n": "^4.51.0",
+		"@wordpress/icons": "^9.42.0",
+		"@wordpress/private-apis": "^0.33.0",
 		"classnames": "^2.3.1"
 	},
 	"peerDependencies": {
@@ -44,5 +47,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "5e6f9caa205d3bfdbac131952b7bf9c6ec60569b"
+	"gitHead": "eb796371e9630636a4a8837033807b0c4a06ed67"
 }

package/src/components/preference-base-option/README.md

@@ -0,0 +1,40 @@
+# PreferenceBaseOption
+
+`PreferenceBaseOption` renders a toggle meant to be used within `PreferencesModal`. 
+
+This component implements a `ToggleControl` component from the `@wordpress/components` package.
+
+## Example
+
+```jsx
+function MyEditorPreferencesOption() {
+	return (
+		<PreferenceBaseOption
+			label={ label }
+			isChecked={ isChecked }
+			onChange={ setIsChecked }
+		>
+			{ isChecked !== areCustomFieldsEnabled && (
+				<CustomFieldsConfirmation willEnable={ isChecked } />
+			) }
+		</PreferenceBaseOption>
+	)				
+}
+```
+
+## Props
+
+### help 
+### label 
+### isChecked 
+### onChange
+
+These props are passed directly to ToggleControl, so see [ToggleControl readme](https://github.com/WordPress/gutenberg/blob/trunk/packages/components/src/toggle-control/README.md) for more info.
+
+### children
+
+Components to be rendered as content.
+
+-   Type: `Element`
+-   Required: No.
+

package/src/components/preference-base-option/index.js

@@ -0,0 +1,21 @@
+/**
+ * WordPress dependencies
+ */
+import { ToggleControl } from '@wordpress/components';
+
+function BaseOption( { help, label, isChecked, onChange, children } ) {
+	return (
+		<div className="preference-base-option">
+			<ToggleControl
+				__nextHasNoMarginBottom
+				help={ help }
+				label={ label }
+				checked={ isChecked }
+				onChange={ onChange }
+			/>
+			{ children }
+		</div>
+	);
+}
+
+export default BaseOption;

package/src/components/preference-base-option/style.scss

@@ -0,0 +1,10 @@
+.preference-base-option {
+	& + & {
+		margin-top: $grid-unit-20;
+	}
+
+	.components-base-control__help {
+		margin-top: 0;
+		margin-left: 48px;
+	}
+}

package/src/components/preference-toggle-control/index.js

@@ -0,0 +1,38 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect, useDispatch } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { store as preferencesStore } from '../../store';
+import PreferenceBaseOption from '../preference-base-option';
+
+function PreferenceToggleControl( props ) {
+	const {
+		scope,
+		featureName,
+		onToggle = () => {},
+		...remainingProps
+	} = props;
+	const isChecked = useSelect(
+		( select ) => !! select( preferencesStore ).get( scope, featureName ),
+		[ scope, featureName ]
+	);
+	const { toggle } = useDispatch( preferencesStore );
+	const onChange = () => {
+		onToggle();
+		toggle( scope, featureName );
+	};
+
+	return (
+		<PreferenceBaseOption
+			onChange={ onChange }
+			isChecked={ isChecked }
+			{ ...remainingProps }
+		/>
+	);
+}
+
+export default PreferenceToggleControl;

package/src/components/preference-toggle-menu-item/index.js

@@ -20,6 +20,7 @@ export default function PreferenceToggleMenuItem( {
 	messageActivated,
 	messageDeactivated,
 	shortcut,
+	handleToggling = true,
 	onToggle = () => null,
 	disabled = false,
 } ) {
@@ -56,7 +57,9 @@ export default function PreferenceToggleMenuItem( {
 			isSelected={ isActive }
 			onClick={ () => {
 				onToggle();
-				toggle( scope, name );
+				if ( handleToggling ) {
+					toggle( scope, name );
+				}
 				speakMessage();
 			} }
 			role="menuitemcheckbox"

package/src/components/preferences-modal/README.md

@@ -0,0 +1,69 @@
+# PreferencesModal
+
+`PreferencesModal` renders a modal with editor preferences. It can take a `PreferencesModalTabs` component, which accepts multiple tabs, and/or other child components. On small viewports, the modal is fullscreen.
+
+This component implements a `Modal` component from the `@wordpress/components` package.
+
+Sections passed to this component should use `PreferencesModalSection` component from the `@wordpress/preferences` package.
+
+
+## Example
+
+```jsx
+function MyEditorPreferencesModal() {
+	const { closeModal } = useDispatch( editPostStore );
+	const sections = [
+		{
+			name: 'section 1',
+			tabLabel: __( 'Section 1' ),
+			content: (
+						<PreferencesModalSection
+							title={ __( 'Publishing' ) }
+							description={ __(
+								'Change options related to publishing.'
+							) }
+						>
+							<EnablePublishSidebarOption
+								help={ __(
+									'Review settings, such as visibility and tags.'
+								) }
+								label={ __(
+									'Enable pre-publish checks'
+								) }
+							/>
+						</PreferencesModalSection>
+					)
+
+		}
+		{
+			name: 'section 2',
+			tabLabel: __( 'Section 2' ),
+			content: (
+						<PreferencesModalSection
+							title={ __( 'Additional' ) }
+							description={ __(
+								'Add extra areas to the editor.'
+							) }
+						>
+							// Section content here
+						</PreferencesModalSection>
+					)
+
+		}
+	]
+	return (
+		<PreferencesModal closeModal={ closeModal }>
+			<PreferencesModalTabs sections={ sections } />
+		<PreferencesModal />
+	);
+}
+```
+
+## Props
+
+### closeModal
+
+A function to call when closing the modal.
+
+-   Type: `Function`
+-   Required: Yes.

package/src/components/preferences-modal/index.js

@@ -0,0 +1,17 @@
+/**
+ * WordPress dependencies
+ */
+import { Modal } from '@wordpress/components';
+import { __ } from '@wordpress/i18n';
+
+export default function PreferencesModal( { closeModal, children } ) {
+	return (
+		<Modal
+			className="preferences-modal"
+			title={ __( 'Preferences' ) }
+			onRequestClose={ closeModal }
+		>
+			{ children }
+		</Modal>
+	);
+}

package/src/components/preferences-modal/style.scss

@@ -0,0 +1,21 @@
+.preferences-modal {
+	// To keep modal dimensions consistent as subsections are navigated, width
+	// and height are used instead of max-(width/height).
+	@include break-small() {
+		width: calc(100% - #{ $grid-unit-20 * 2 });
+		height: calc(100% - #{ $header-height * 2 });
+	}
+	@include break-medium() {
+		width: $break-medium - $grid-unit-20 * 2;
+	}
+	@include break-large() {
+		height: 70%;
+	}
+
+	// Clears spacing to flush fit the navigator component to the modal edges.
+	@media (max-width: #{ ($break-medium - 1) }) {
+		.components-modal__content {
+			padding: 0;
+		}
+	}
+}

package/src/components/preferences-modal-section/README.md

@@ -0,0 +1,31 @@
+# PreferencesModalSection
+
+`PreferencesModalSection` renders a section (as a fieldset) meant to be used with `PreferencesModal`.
+
+## Example
+
+See the `PreferencesModal` readme for usage info.
+
+
+## Props
+
+### title
+
+The title of the section
+
+-   Type: `String`
+-   Required: Yes.
+
+### description
+
+The description for the section.
+
+-   Type: `String`
+-   Required: No.
+
+### children
+
+Components to be rendered as content.
+
+-   Type: `Element`
+-   Required: Yes.

package/src/components/preferences-modal-section/index.js

@@ -0,0 +1,15 @@
+const Section = ( { description, title, children } ) => (
+	<fieldset className="preferences-modal__section">
+		<legend className="preferences-modal__section-legend">
+			<h2 className="preferences-modal__section-title">{ title }</h2>
+			{ description && (
+				<p className="preferences-modal__section-description">
+					{ description }
+				</p>
+			) }
+		</legend>
+		<div className="preferences-modal__section-content">{ children }</div>
+	</fieldset>
+);
+
+export default Section;

package/src/components/preferences-modal-section/style.scss

@@ -0,0 +1,28 @@
+.preferences-modal__section {
+	margin: 0 0 2.5rem 0;
+
+	&:last-child {
+		margin: 0;
+	}
+}
+
+.preferences-modal__section-legend {
+	margin-bottom: $grid-unit-10;
+}
+
+.preferences-modal__section-title {
+	font-size: 0.9rem;
+	font-weight: 600;
+	margin-top: 0;
+}
+
+.preferences-modal__section-description {
+	margin: -$grid-unit-10 0 $grid-unit-10 0;
+	font-size: $helptext-font-size;
+	font-style: normal;
+	color: $gray-700;
+}
+
+.preferences-modal__section:has(.preferences-modal__section-content:empty) {
+	display: none;
+}

package/src/components/preferences-modal-tabs/README.md

@@ -0,0 +1,14 @@
+# PreferencesModalTabs
+
+`PreferencesModalTabs` creates a tabbed interface meant to be used inside a `PreferencesModal`. Markup differs between small and large viewports; on small the tabs are closed by default.
+
+## Example
+
+See the `PreferencesModal` readme for usage info.
+## Props
+### sections
+
+Sections to populate the modal with. Takes an array of objects, where each should include `name`, `tablabel` and `content`.
+
+-   Type: `Array`
+-   Required: Yes.