@wordpress/preferences 3.26.0 → 3.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/preferences",
-	"version": "3.26.0",
+	"version": "3.27.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.50.0",
+		"@wordpress/components": "^25.16.0",
+		"@wordpress/compose": "^6.27.0",
+		"@wordpress/data": "^9.20.0",
+		"@wordpress/deprecated": "^3.50.0",
+		"@wordpress/element": "^5.27.0",
+		"@wordpress/i18n": "^4.50.0",
+		"@wordpress/icons": "^9.41.0",
+		"@wordpress/private-apis": "^0.32.0",
 		"classnames": "^2.3.1"
 	},
 	"peerDependencies": {
@@ -44,5 +47,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "5e6f9caa205d3bfdbac131952b7bf9c6ec60569b"
+	"gitHead": "45de2cb4212fed7f2763e95f10300d1ff9d0ec08"
 }

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/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.

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

@@ -0,0 +1,178 @@
+/**
+ * WordPress dependencies
+ */
+import { useViewportMatch } from '@wordpress/compose';
+import {
+	__experimentalNavigatorProvider as NavigatorProvider,
+	__experimentalNavigatorScreen as NavigatorScreen,
+	__experimentalNavigatorButton as NavigatorButton,
+	__experimentalNavigatorBackButton as NavigatorBackButton,
+	__experimentalItemGroup as ItemGroup,
+	__experimentalItem as Item,
+	__experimentalHStack as HStack,
+	__experimentalText as Text,
+	__experimentalTruncate as Truncate,
+	FlexItem,
+	Card,
+	CardHeader,
+	CardBody,
+	privateApis as componentsPrivateApis,
+} from '@wordpress/components';
+import { useMemo, useState } from '@wordpress/element';
+import { chevronLeft, chevronRight, Icon } from '@wordpress/icons';
+import { isRTL, __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../lock-unlock';
+
+const { Tabs } = unlock( componentsPrivateApis );
+
+const PREFERENCES_MENU = 'preferences-menu';
+
+export default function PreferencesModalTabs( { sections } ) {
+	const isLargeViewport = useViewportMatch( 'medium' );
+
+	// This is also used to sync the two different rendered components
+	// between small and large viewports.
+	const [ activeMenu, setActiveMenu ] = useState( PREFERENCES_MENU );
+	/**
+	 * Create helper objects from `sections` for easier data handling.
+	 * `tabs` is used for creating the `Tabs` and `sectionsContentMap`
+	 * is used for easier access to active tab's content.
+	 */
+	const { tabs, sectionsContentMap } = useMemo( () => {
+		let mappedTabs = {
+			tabs: [],
+			sectionsContentMap: {},
+		};
+		if ( sections.length ) {
+			mappedTabs = sections.reduce(
+				( accumulator, { name, tabLabel: title, content } ) => {
+					accumulator.tabs.push( { name, title } );
+					accumulator.sectionsContentMap[ name ] = content;
+					return accumulator;
+				},
+				{ tabs: [], sectionsContentMap: {} }
+			);
+		}
+		return mappedTabs;
+	}, [ sections ] );
+
+	let modalContent;
+	// We render different components based on the viewport size.
+	if ( isLargeViewport ) {
+		modalContent = (
+			<div className="preferences__tabs">
+				<Tabs
+					initialTabId={
+						activeMenu !== PREFERENCES_MENU ? activeMenu : undefined
+					}
+					onSelect={ setActiveMenu }
+					orientation="vertical"
+				>
+					<Tabs.TabList className="preferences__tabs-tablist">
+						{ tabs.map( ( tab ) => (
+							<Tabs.Tab
+								tabId={ tab.name }
+								key={ tab.name }
+								className="preferences__tabs-tab"
+							>
+								{ tab.title }
+							</Tabs.Tab>
+						) ) }
+					</Tabs.TabList>
+					{ tabs.map( ( tab ) => (
+						<Tabs.TabPanel
+							tabId={ tab.name }
+							key={ tab.name }
+							className="preferences__tabs-tabpanel"
+							focusable={ false }
+						>
+							{ sectionsContentMap[ tab.name ] || null }
+						</Tabs.TabPanel>
+					) ) }
+				</Tabs>
+			</div>
+		);
+	} else {
+		modalContent = (
+			<NavigatorProvider
+				initialPath="/"
+				className="preferences__provider"
+			>
+				<NavigatorScreen path="/">
+					<Card isBorderless size="small">
+						<CardBody>
+							<ItemGroup>
+								{ tabs.map( ( tab ) => {
+									return (
+										<NavigatorButton
+											key={ tab.name }
+											path={ tab.name }
+											as={ Item }
+											isAction
+										>
+											<HStack justify="space-between">
+												<FlexItem>
+													<Truncate>
+														{ tab.title }
+													</Truncate>
+												</FlexItem>
+												<FlexItem>
+													<Icon
+														icon={
+															isRTL()
+																? chevronLeft
+																: chevronRight
+														}
+													/>
+												</FlexItem>
+											</HStack>
+										</NavigatorButton>
+									);
+								} ) }
+							</ItemGroup>
+						</CardBody>
+					</Card>
+				</NavigatorScreen>
+				{ sections.length &&
+					sections.map( ( section ) => {
+						return (
+							<NavigatorScreen
+								key={ `${ section.name }-menu` }
+								path={ section.name }
+							>
+								<Card isBorderless size="large">
+									<CardHeader
+										isBorderless={ false }
+										justify="left"
+										size="small"
+										gap="6"
+									>
+										<NavigatorBackButton
+											icon={
+												isRTL()
+													? chevronRight
+													: chevronLeft
+											}
+											aria-label={ __(
+												'Navigate to the previous view'
+											) }
+										/>
+										<Text size="16">
+											{ section.tabLabel }
+										</Text>
+									</CardHeader>
+									<CardBody>{ section.content }</CardBody>
+								</Card>
+							</NavigatorScreen>
+						);
+					} ) }
+			</NavigatorProvider>
+		);
+	}
+
+	return modalContent;
+}

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

@@ -0,0 +1,48 @@
+$vertical-tabs-width: 160px;
+
+.preferences__tabs-tablist {
+	position: absolute;
+	top: $header-height + $grid-unit-30;
+	// Aligns button text instead of button box.
+	left: $grid-unit-20;
+	width: $vertical-tabs-width;
+
+}
+
+.preferences__tabs-tab {
+	border-radius: $radius-block-ui;
+	font-weight: 400;
+
+	&[aria-selected="true"] {
+		background: $gray-100;
+		box-shadow: none;
+		font-weight: 500;
+	}
+
+	&[aria-selected="true"]::after {
+		content: none;
+	}
+
+	&[role="tab"]:focus:not(:disabled) {
+		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color);
+		// Windows high contrast mode.
+		outline: 2px solid transparent;
+	}
+
+	&:focus-visible::before {
+		content: none;
+	}
+}
+
+.preferences__tabs-tabpanel {
+	padding-left: $grid-unit-30;
+	margin-left: $vertical-tabs-width;
+}
+
+@media (max-width: #{ ($break-medium - 1) }) {
+	// Keep the navigator component from overflowing the modal content area
+	// to ensure that sticky position elements stick where intended.
+	.preferences__provider {
+		height: 100%;
+	}
+}

package/src/index.js

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

package/src/lock-unlock.js

@@ -0,0 +1,9 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I know using unstable features means my theme or plugin will inevitably break in the next version of WordPress.',
+		'@wordpress/preferences'
+	);

package/src/private-apis.js

@@ -0,0 +1,18 @@
+/**
+ * Internal dependencies
+ */
+import PreferenceBaseOption from './components/preference-base-option';
+import PreferenceToggleControl from './components/preference-toggle-control';
+import PreferencesModal from './components/preferences-modal';
+import PreferencesModalSection from './components/preferences-modal-section';
+import PreferencesModalTabs from './components/preferences-modal-tabs';
+import { lock } from './lock-unlock';
+
+export const privateApis = {};
+lock( privateApis, {
+	PreferenceBaseOption,
+	PreferenceToggleControl,
+	PreferencesModal,
+	PreferencesModalSection,
+	PreferencesModalTabs,
+} );

package/src/store/index.js

@@ -12,7 +12,7 @@ import * as selectors from './selectors';
 import { STORE_NAME } from './constants';
 
 /**
- * Store definition for the interface namespace.
+ * Store definition for the preferences namespace.
  *
  * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore
  *

package/src/store/selectors.js

@@ -1,3 +1,43 @@
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+
+const withDeprecatedKeys = ( originalGet ) => ( state, scope, name ) => {
+	const settingsToMoveToCore = [
+		'allowRightClickOverrides',
+		'distractionFree',
+		'editorMode',
+		'fixedToolbar',
+		'focusMode',
+		'hiddenBlockTypes',
+		'inactivePanels',
+		'keepCaretInsideBlock',
+		'mostUsedBlocks',
+		'openPanels',
+		'showBlockBreadcrumbs',
+		'showIconLabels',
+		'showListViewByDefault',
+	];
+
+	if (
+		settingsToMoveToCore.includes( name ) &&
+		[ 'core/edit-post', 'core/edit-site' ].includes( scope )
+	) {
+		deprecated(
+			`wp.data.select( 'core/preferences' ).get( '${ scope }', '${ name }' )`,
+			{
+				since: '6.5',
+				alternative: `wp.data.select( 'core/preferences' ).get( 'core', '${ name }' )`,
+			}
+		);
+
+		return originalGet( state, 'core', name );
+	}
+
+	return originalGet( state, scope, name );
+};
+
 /**
  * Returns a boolean indicating whether a prefer is active for a particular
  * scope.
@@ -8,7 +48,7 @@
  *
  * @return {*} Is the feature enabled?
  */
-export function get( state, scope, name ) {
+export const get = withDeprecatedKeys( ( state, scope, name ) => {
 	const value = state.preferences[ scope ]?.[ name ];
 	return value !== undefined ? value : state.defaults[ scope ]?.[ name ];
-}
+} );

package/src/style.scss

@@ -0,0 +1,4 @@
+@import "./components/preference-base-option/style.scss";
+@import "./components/preferences-modal/style.scss";
+@import "./components/preferences-modal-tabs/style.scss";
+@import "./components/preferences-modal-section/style.scss";