lock() the Global Styles APIs

packages/block-editor/README.md

@@ -348,6 +348,10 @@ _Returns_
 
 Undocumented declaration.
 
+### experiments
+
+Experimental @wordpress/block-editor APIs.
+
 ### FontSizePicker
 
 _Related_
@@ -527,10 +531,6 @@ _Returns_
 
 - `Object`: Typography block support derived CSS classes & styles.
 
-### GlobalStylesContext
-
-Undocumented declaration.
-
 ### InnerBlocks
 
 _Related_
@@ -792,18 +792,6 @@ _Returns_
 
 - `any`: value
 
-### useGlobalStylesOutput
-
-Undocumented declaration.
-
-### useGlobalStylesReset
-
-Undocumented declaration.
-
-### useGlobalStylesSetting
-
-Undocumented declaration.
-
 ### useInnerBlocksProps
 
 This hook is used to lightly mark an element as an inner blocks wrapper
@@ -844,10 +832,6 @@ _Returns_
 
 - `any`: Returns the value defined for the setting.
 
-### useStyle
-
-Undocumented declaration.
-
 ### Warning
 
 _Related_

packages/block-editor/package.json

@@ -45,6 +45,7 @@
  "@wordpress/dom": "file:../dom",
  "@wordpress/element": "file:../element",
  "@wordpress/escape-html": "file:../escape-html",
+ "@wordpress/experiments": "file:../experiments",
  "@wordpress/hooks": "file:../hooks",
  "@wordpress/html-entities": "file:../html-entities",
  "@wordpress/i18n": "file:../i18n",

packages/block-editor/src/components/global-styles/README.md

@@ -39,39 +39,39 @@ function MyComponent() {
 }
 ```
 
-## useStyle
+## useGlobalStyle
 
 A react hook used to retrieve the style applied to a given context.
 
 ```js
-import { useStyle } from '@wordpress/block-editor';
+import { useGlobalStyle } from '@wordpress/block-editor';
 
 function MyComponent() {
  // Text color for the site root.
- const [ color, setColor ] = useStyle( 'color.text' ); 
+ const [ color, setColor ] = useGlobalStyle( 'color.text' ); 
 
  // The user modified color for the core paragraph block.
- const [ pColor, setPColor ] = useStyle( 'color.text', 'core/paragraph', 'user' ); 
+ const [ pColor, setPColor ] = useGlobalStyle( 'color.text', 'core/paragraph', 'user' ); 
 
  return "Something";
 }
 ```
 
-## useSetting
+## useGlobalSetting
 
 A react hook used to retrieve the setting applied to a given context.
 
 ```js
-import { useGlobalStylesSetting as useSetting } from '@wordpress/block-editor';
+import { useGlobalSetting } from '@wordpress/block-editor';
 
 function MyComponent() {
  // The default color palette.
- const [ colorPalette, setColorPalette ] = useSetting( 'color.palette' ); 
+ const [ colorPalette, setColorPalette ] = useGlobalSetting( 'color.palette' ); 
 
  // The base (theme + core) color palette for the paragraph block,
  // ignoring user provided palette.
  // If the palette is not defined for the paragraph block, the root one is returned.
- const [ pColor, setPColor ] = useSetting( 'color.palette', 'core/paragraph', 'base' ); 
+ const [ pColor, setPColor ] = useGlobalSetting( 'color.palette', 'core/paragraph', 'base' ); 
 
  return "Something";
 }

packages/block-editor/src/components/global-styles/hooks.js

@@ -30,7 +30,7 @@ export const useGlobalStylesReset = () => {
  ];
 };
 
-export function useSetting( path, blockName, source = 'all' ) {
+export function useGlobalSetting( path, blockName, source = 'all' ) {
  const {
  merged: mergedConfig,
  base: baseConfig,
@@ -93,7 +93,7 @@ export function useSetting( path, blockName, source = 'all' ) {
  return [ resultWithFallback, setSetting ];
 }
 
-export function useStyle( path, blockName, source = 'all' ) {
+export function useGlobalStyle( path, blockName, source = 'all' ) {
  const {
  merged: mergedConfig,
  base: baseConfig,

packages/block-editor/src/components/global-styles/index.js

@@ -1,8 +1,7 @@
-// TODO: Should probably __experimental these.
 export {
  useGlobalStylesReset,
- useStyle,
- useSetting as useGlobalStylesSetting, // TODO: Naming conflict with useSetting from @wordpress/block-editor. Are they the same function?
+ useGlobalSetting,
+ useGlobalStyle,
 } from './hooks';
 export { useGlobalStylesOutput } from './use-global-styles-output';
 export { GlobalStylesContext } from './context';

packages/block-editor/src/components/global-styles/use-global-styles-output.js

@@ -22,7 +22,7 @@ import { getCSSRules } from '@wordpress/style-engine';
 import { PRESET_METADATA, ROOT_BLOCK_SELECTOR, scopeSelector } from './utils';
 import { getTypographyFontSizeValue } from './typography-utils';
 import { GlobalStylesContext } from './context';
-import { useSetting } from './hooks';
+import { useGlobalSetting } from './hooks';
 import { PresetDuotoneFilter } from '../duotone/components';
 import { getGapCSSValue } from '../../hooks/gap';
 import { store as blockEditorStore } from '../../store';
@@ -997,7 +997,7 @@ function updateConfigWithSeparator( config ) {
 export function useGlobalStylesOutput() {
  let { merged: mergedConfig } = useContext( GlobalStylesContext );
 
- const [ blockGap ] = useSetting( 'spacing.blockGap' );
+ const [ blockGap ] = useGlobalSetting( 'spacing.blockGap' );
  const hasBlockGapSupport = blockGap !== null;
  const hasFallbackGapSupport = ! hasBlockGapSupport; // This setting isn't useful yet: it exists as a placeholder for a future explicit fallback styles support.
  const disableLayoutStyles = useSelect( ( select ) => {

packages/block-editor/src/components/index.js

@@ -161,4 +161,3 @@ export { default as __experimentalInspectorPopoverHeader } from './inspector-pop
 
 export { default as BlockEditorProvider } from './provider';
 export { default as useSetting } from './use-setting';
-export * from './global-styles'; // TODO: Should this instead be in @wordpress/global-styles?

packages/block-editor/src/experiments.js

@@ -0,0 +1,23 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/experiments';
+
+/**
+ * Internal dependencies
+ */
+import * as globalStyles from './components/global-styles';
+
+export const { lock, unlock } =
+ __dangerousOptInToUnstableAPIsOnlyForCoreModules(
+ 'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
+ '@wordpress/block-editor'
+ );
+
+/**
+ * Experimental @wordpress/block-editor APIs.
+ */
+export const experiments = {};
+lock( experiments, {
+ ...globalStyles,
+} );

packages/block-editor/src/index.js

@@ -20,3 +20,4 @@ export * from './elements';
 export * from './utils';
 export { storeConfig, store } from './store';
 export { SETTINGS_DEFAULTS } from './store/defaults';
+export { experiments } from './experiments';

packages/edit-site/package.json

@@ -39,6 +39,7 @@
  "@wordpress/deprecated": "file:../deprecated",
  "@wordpress/editor": "file:../editor",
  "@wordpress/element": "file:../element",
+ "@wordpress/experiments": "file:../experiments",
  "@wordpress/hooks": "file:../hooks",
  "@wordpress/html-entities": "file:../html-entities",
  "@wordpress/i18n": "file:../i18n",

packages/edit-site/src/components/global-styles-renderer/index.js

@@ -3,12 +3,15 @@
  */
 import { useEffect } from '@wordpress/element';
 import { useSelect, useDispatch } from '@wordpress/data';
-import { useGlobalStylesOutput } from '@wordpress/block-editor';
+import { experiments as blockEditorExperiments } from '@wordpress/block-editor';
 
 /**
  * Internal dependencies
  */
 import { store as editSiteStore } from '../../store';
+import { unlock } from '../../experiments';
+
+const { useGlobalStylesOutput } = unlock( blockEditorExperiments );
 
 function useGlobalStylesRenderer() {
  const [ styles, settings, svgFilters ] = useGlobalStylesOutput();

packages/edit-site/src/components/global-styles/border-panel.js

@@ -3,8 +3,7 @@
  */
 import {
  __experimentalBorderRadiusControl as BorderRadiusControl,
- useGlobalStylesSetting as useSetting,
- useStyle,
+ experiments as blockEditorExperiments,
 } from '@wordpress/block-editor';
 import {
  __experimentalBorderBoxControl as BorderBoxControl,
@@ -20,6 +19,9 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { getSupportedGlobalStylesPanels, useColorsPerOrigin } from './hooks';
+import { unlock } from '../../experiments';
+
+const { useGlobalSetting, useGlobalStyle } = unlock( blockEditorExperiments );
 
 export function useHasBorderPanel( name ) {
  const controls = [
@@ -35,31 +37,31 @@ export function useHasBorderPanel( name ) {
 function useHasBorderColorControl( name ) {
  const supports = getSupportedGlobalStylesPanels( name );
  return (
- useSetting( 'border.color', name )[ 0 ] &&
+ useGlobalSetting( 'border.color', name )[ 0 ] &&
  supports.includes( 'borderColor' )
  );
 }
 
 function useHasBorderRadiusControl( name ) {
  const supports = getSupportedGlobalStylesPanels( name );
  return (
- useSetting( 'border.radius', name )[ 0 ] &&
+ useGlobalSetting( 'border.radius', name )[ 0 ] &&
  supports.includes( 'borderRadius' )
  );
 }
 
 function useHasBorderStyleControl( name ) {
  const supports = getSupportedGlobalStylesPanels( name );
  return (
- useSetting( 'border.style', name )[ 0 ] &&
+ useGlobalSetting( 'border.style', name )[ 0 ] &&
  supports.includes( 'borderStyle' )
  );
 }
 
 function useHasBorderWidthControl( name ) {
  const supports = getSupportedGlobalStylesPanels( name );
  return (
- useSetting( 'border.width', name )[ 0 ] &&
+ useGlobalSetting( 'border.width', name )[ 0 ] &&
  supports.includes( 'borderWidth' )
  );
 }
@@ -96,12 +98,15 @@ function applyAllFallbackStyles( border ) {
 export default function BorderPanel( { name, variationPath = '' } ) {
  // To better reflect if the user has customized a value we need to
  // ensure the style value being checked is from the `user` origin.
- const [ userBorderStyles ] = useStyle(
+ const [ userBorderStyles ] = useGlobalStyle(
  `${ variationPath }border`,
  name,
  'user'
  );
- const [ border, setBorder ] = useStyle( `${ variationPath }border`, name );
+ const [ border, setBorder ] = useGlobalStyle(
+ `${ variationPath }border`,
+ name
+ );
  const colors = useColorsPerOrigin( name );
 
  const showBorderColor = useHasBorderColorControl( name );
@@ -110,7 +115,7 @@ export default function BorderPanel( { name, variationPath = '' } ) {
 
  // Border radius.
  const showBorderRadius = useHasBorderRadiusControl( name );
- const [ borderRadiusValues, setBorderRadius ] = useStyle(
+ const [ borderRadiusValues, setBorderRadius ] = useGlobalStyle(
  `${ variationPath }border.radius`,
  name
  );

packages/edit-site/src/components/global-styles/color-palette-panel.js

@@ -6,33 +6,40 @@ import {
  __experimentalVStack as VStack,
 } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
-import { useGlobalStylesSetting as useSetting } from '@wordpress/block-editor';
+import { experiments as blockEditorExperiments } from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../experiments';
+
+const { useGlobalSetting } = unlock( blockEditorExperiments );
 
 export default function ColorPalettePanel( { name } ) {
- const [ themeColors, setThemeColors ] = useSetting(
+ const [ themeColors, setThemeColors ] = useGlobalSetting(
  'color.palette.theme',
  name
  );
- const [ baseThemeColors ] = useSetting(
+ const [ baseThemeColors ] = useGlobalSetting(
  'color.palette.theme',
  name,
  'base'
  );
- const [ defaultColors, setDefaultColors ] = useSetting(
+ const [ defaultColors, setDefaultColors ] = useGlobalSetting(
  'color.palette.default',
  name
  );
- const [ baseDefaultColors ] = useSetting(
+ const [ baseDefaultColors ] = useGlobalSetting(
  'color.palette.default',
  name,
  'base'
  );
- const [ customColors, setCustomColors ] = useSetting(
+ const [ customColors, setCustomColors ] = useGlobalSetting(
  'color.palette.custom',
  name
  );
 
- const [ defaultPaletteEnabled ] = useSetting(
+ const [ defaultPaletteEnabled ] = useGlobalSetting(
  'color.defaultPalette',
  name
  );

packages/edit-site/src/components/global-styles/custom-css.js

@@ -8,11 +8,18 @@ import {
  PanelBody,
 } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
-import { useStyle } from '@wordpress/block-editor';
+import { experiments as blockEditorExperiments } from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from '../../experiments';
+
+const { useGlobalStyle } = unlock( blockEditorExperiments );
 
 function CustomCSSControl() {
- const [ customCSS, setCustomCSS ] = useStyle( 'css' );
- const [ themeCSS ] = useStyle( 'css', null, 'base' );
+ const [ customCSS, setCustomCSS ] = useGlobalStyle( 'css' );
+ const [ themeCSS ] = useGlobalStyle( 'css', null, 'base' );
  const ignoreThemeCustomCSS = '/* IgnoreThemeCustomCSS */';
 
  // If there is custom css from theme.json show it in the edit box