@wordpress/block-editor 16.0.1-next.v.202607070741.0 → 16.2.0

package/src/components/global-styles/inheritance/test/index.js

@@ -0,0 +1,270 @@
+import { render, screen } from '@testing-library/react';
+import { click } from '@ariakit/test';
+import { __experimentalToolsPanel as ToolsPanel } from '@wordpress/components';
+import {
+	getInheritanceProps,
+	InheritanceResetButton,
+	InheritanceToolsPanelItem,
+} from '../';
+
+describe( 'InheritanceResetButton', () => {
+	test( 'renders an always-visible reset button labelled for the inherited value', () => {
+		render( <InheritanceResetButton onResetToInherited={ () => {} } /> );
+		expect(
+			screen.getByRole( 'button', {
+				name: 'Reset to inherited value',
+			} )
+		).toBeVisible();
+	} );
+
+	test( 'invokes the reset handler when activated', async () => {
+		const onResetToInherited = jest.fn();
+		render(
+			<InheritanceResetButton onResetToInherited={ onResetToInherited } />
+		);
+		await click(
+			screen.getByRole( 'button', { name: 'Reset to inherited value' } )
+		);
+		expect( onResetToInherited ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'does not expose a menu or a push-to-Global-Styles action', () => {
+		render( <InheritanceResetButton onResetToInherited={ () => {} } /> );
+		expect( screen.queryByRole( 'menu' ) ).not.toBeInTheDocument();
+		expect(
+			screen.queryByRole( 'menuitem', { name: /Make default/ } )
+		).not.toBeInTheDocument();
+	} );
+} );
+
+describe( 'getInheritanceProps', () => {
+	test( 'returns explicit false state when neither flag is set', () => {
+		expect( getInheritanceProps( false, false ) ).toEqual( {
+			isInherited: false,
+			hasLocalOverride: false,
+		} );
+	} );
+
+	test( 'returns ONLY the inherited className when isInherited is set', () => {
+		// The inherited state is conveyed purely through the className hook
+		// (`is-inherited-from-global-styles`), which the SCSS uses to apply
+		// the dotted-underline label treatment. No dot is rendered.
+		expect( getInheritanceProps( true, false ) ).toEqual( {
+			className: 'is-inherited-from-global-styles',
+			isInherited: true,
+			hasLocalOverride: false,
+		} );
+	} );
+
+	test( 'returns the local-override className when hasLocalOverride is set', () => {
+		expect( getInheritanceProps( false, true ) ).toEqual( {
+			className: 'has-local-override-from-global-styles',
+			isInherited: false,
+			hasLocalOverride: true,
+		} );
+	} );
+
+	test( 'returns ONLY the local-override className when both flags are passed (mutual exclusion)', () => {
+		// A buggy caller could pass both as `true`. The visual
+		// contract is mutual exclusion — local-override always wins.
+		const result = getInheritanceProps( true, true );
+		expect( result.className ).toContain(
+			'has-local-override-from-global-styles'
+		);
+		expect( result.isInherited ).toBe( false );
+		expect( result.hasLocalOverride ).toBe( true );
+	} );
+
+	test( 'coerces truthy/falsy non-boolean inputs', () => {
+		// Common pattern: callers pass an undefined or null inherited
+		// value that we want to treat as "no local override" rather
+		// than letting it slip through as truthy.
+		expect( getInheritanceProps( undefined, undefined ) ).toEqual( {
+			isInherited: false,
+			hasLocalOverride: false,
+		} );
+		expect( getInheritanceProps( null, null ) ).toEqual( {
+			isInherited: false,
+			hasLocalOverride: false,
+		} );
+		expect( getInheritanceProps( '', '' ) ).toEqual( {
+			isInherited: false,
+			hasLocalOverride: false,
+		} );
+		// Truthy non-boolean
+		expect( getInheritanceProps( 'inherited', 0 ) ).toEqual( {
+			className: 'is-inherited-from-global-styles',
+			isInherited: true,
+			hasLocalOverride: false,
+		} );
+		expect( getInheritanceProps( 0, 'local' ) ).toEqual( {
+			className: 'has-local-override-from-global-styles',
+			isInherited: false,
+			hasLocalOverride: true,
+		} );
+	} );
+
+	test( 'merges a base className with the inherited class hook', () => {
+		expect( getInheritanceProps( true, false, 'single-column' ) ).toEqual( {
+			className: 'single-column is-inherited-from-global-styles',
+			isInherited: true,
+			hasLocalOverride: false,
+		} );
+	} );
+
+	test( 'merges a base className with the local-override class hook', () => {
+		expect( getInheritanceProps( false, true, 'single-column' ) ).toEqual( {
+			className: 'single-column has-local-override-from-global-styles',
+			isInherited: false,
+			hasLocalOverride: true,
+		} );
+	} );
+
+	test( 'returns just the base className when neither flag is set', () => {
+		expect( getInheritanceProps( false, false, 'single-column' ) ).toEqual(
+			{
+				className: 'single-column',
+				isInherited: false,
+				hasLocalOverride: false,
+			}
+		);
+	} );
+} );
+
+describe( 'InheritanceToolsPanelItem inherited state', () => {
+	function renderInheritedItem( label, labelClassName ) {
+		return render(
+			<ToolsPanel label="Panel" panelId="panel">
+				<InheritanceToolsPanelItem
+					{ ...getInheritanceProps( true, false ) }
+					label={ label }
+					panelId="panel"
+					isShownByDefault
+					hasValue={ () => false }
+				>
+					<div className={ labelClassName }>{ label }</div>
+				</InheritanceToolsPanelItem>
+			</ToolsPanel>
+		);
+	}
+
+	// The SCSS treatment keys off the label class, and controls on a bare
+	// `UnitControl`/`NumberControl` expose `input-control__label` rather than
+	// the usual `base-control__label`, so guard both.
+	test.each( [
+		[ 'base-control', 'components-base-control__label' ],
+		[ 'input-control', 'components-input-control__label' ],
+	] )(
+		'nests the %s label inside the inherited-from-global-styles item',
+		( _name, labelClassName ) => {
+			renderInheritedItem( 'Line height', labelClassName );
+			const label = screen.getByText( 'Line height' );
+			expect( label ).toHaveClass( labelClassName );
+			expect(
+				// eslint-disable-next-line testing-library/no-node-access
+				label.closest( '.is-inherited-from-global-styles' )
+			).not.toBeNull();
+		}
+	);
+
+	test( 'does not render a reset dot in the inherited state', () => {
+		renderInheritedItem( 'Line height', 'components-base-control__label' );
+		expect(
+			screen.queryByRole( 'button', {
+				name: 'Reset to inherited value',
+			} )
+		).not.toBeInTheDocument();
+	} );
+} );
+
+describe( 'InheritanceToolsPanelItem local-override reset dot', () => {
+	function renderItem( props ) {
+		return render(
+			<ToolsPanel label="Panel" panelId="panel">
+				<InheritanceToolsPanelItem
+					label="Line height"
+					panelId="panel"
+					isShownByDefault
+					hasValue={ () => false }
+					{ ...props }
+				>
+					<div className="components-base-control__label">
+						Line height
+					</div>
+				</InheritanceToolsPanelItem>
+			</ToolsPanel>
+		);
+	}
+
+	test( 'renders the reset dot as a sibling of the control, not inside the label', () => {
+		renderItem( {
+			hasLocalOverride: true,
+			onDeselect: () => {},
+		} );
+		const resetButton = screen.getByRole( 'button', {
+			name: 'Reset to inherited value',
+		} );
+		expect( resetButton ).toBeVisible();
+
+		// The reset dot is a plain sibling; it must never be nested inside
+		// the label (which would create an interactive-in-label a11y issue).
+		expect(
+			// eslint-disable-next-line testing-library/no-node-access
+			resetButton.closest( '.components-base-control__label' )
+		).toBeNull();
+	} );
+
+	test( 'does not render the item reset dot when showLocalOverrideActionsInLabel is false', () => {
+		// Color/background render their own reset control next to a custom
+		// toggle, so the item must not render a second one.
+		renderItem( {
+			hasLocalOverride: true,
+			showLocalOverrideActionsInLabel: false,
+			onDeselect: () => {},
+		} );
+		expect(
+			screen.queryByRole( 'button', {
+				name: 'Reset to inherited value',
+			} )
+		).not.toBeInTheDocument();
+	} );
+
+	test( 'the reset dot invokes the deselect handler', async () => {
+		const onDeselect = jest.fn();
+		renderItem( { hasLocalOverride: true, onDeselect } );
+		await click(
+			screen.getByRole( 'button', { name: 'Reset to inherited value' } )
+		);
+		expect( onDeselect ).toHaveBeenCalled();
+	} );
+
+	test( 'does not offset the reset dot by default', () => {
+		renderItem( { hasLocalOverride: true, onDeselect: () => {} } );
+		const resetButton = screen.getByRole( 'button', {
+			name: 'Reset to inherited value',
+		} );
+		const affordance =
+			// eslint-disable-next-line testing-library/no-node-access
+			resetButton.closest( '.global-styles-inheritance-affordance' );
+		expect( affordance ).not.toHaveClass(
+			'global-styles-inheritance-affordance--offset-toggle'
+		);
+	} );
+
+	test( 'offsets the reset dot when the control has an inline-end toggle', () => {
+		renderItem( {
+			hasLocalOverride: true,
+			hasInlineEndToggle: true,
+			onDeselect: () => {},
+		} );
+		const resetButton = screen.getByRole( 'button', {
+			name: 'Reset to inherited value',
+		} );
+		const affordance =
+			// eslint-disable-next-line testing-library/no-node-access
+			resetButton.closest( '.global-styles-inheritance-affordance' );
+		expect( affordance ).toHaveClass(
+			'global-styles-inheritance-affordance--offset-toggle'
+		);
+	} );
+} );

package/src/components/global-styles/inherited-value-context.js

@@ -0,0 +1,264 @@
+import { useContext, useMemo } from '@wordpress/element';
+import { useSelect } from '@wordpress/data';
+import { store as blocksStore } from '@wordpress/blocks';
+import { privateApis as globalStylesEnginePrivateApis } from '@wordpress/global-styles-engine';
+import { store as blockEditorStore } from '../../store';
+import {
+	globalStylesDataKey,
+	globalStylesLinksDataKey,
+} from '../../store/private-keys';
+import { getVariationNameFromClass } from '../../hooks/block-style-variation';
+import { useBlockEditContext } from '../block-edit/context';
+import BlockContext from '../block-context';
+import { unlock } from '../../lock-unlock';
+import { isGlobalStylesInheritanceEnabled } from './inheritance';
+
+const { resolveStyle } = unlock( globalStylesEnginePrivateApis );
+
+// Undefined so the panels fall back to their `inheritedValue = value` default.
+const NO_RESOLVED_STYLE = { value: undefined, sources: undefined };
+
+/**
+ * Reads the Global Styles payload and returns it as a `GlobalStylesConfig`
+ * (`{ styles, _links }`), the shape `resolveStyle` expects. `_links` carries
+ * the theme-file map used to resolve pointers such as background images.
+ *
+ * @return {?Object} Global Styles config, or `null` before the payload settles.
+ */
+function useRawGlobalStyles() {
+	const { rawGlobalStylesData, links } = useSelect( ( select ) => {
+		const settings = select( blockEditorStore ).getSettings();
+		return {
+			rawGlobalStylesData: settings[ globalStylesDataKey ] ?? null,
+			links: settings[ globalStylesLinksDataKey ] ?? null,
+		};
+	}, [] );
+	return useMemo(
+		() =>
+			rawGlobalStylesData
+				? { styles: rawGlobalStylesData, _links: links ?? undefined }
+				: null,
+		[ rawGlobalStylesData, links ]
+	);
+}
+
+/**
+ * Blocks whose heading level is handed down by a parent through block context
+ * rather than held in their own `level` attribute, mapped to that context key
+ * and the level they fall back to.
+ *
+ * Accordion Heading is the only one: the parent Accordion owns the level, and
+ * the child's `level` attribute has no default and is absent on pattern-,
+ * template- and paste-inserted blocks.
+ */
+const CONTEXT_HEADING_LEVEL_BLOCKS = {
+	'core/accordion-heading': {
+		contextKey: 'core/accordion-heading-level',
+		fallbackLevel: 3,
+	},
+};
+
+/**
+ * Resolves the heading level that selects a block's `h1`-`h6` element layer.
+ *
+ * @param {string}  blockName      Block name.
+ * @param {?number} levelAttribute The block's own `level` attribute, if it has one.
+ * @param {?number} contextLevel   Level supplied by a parent through block context.
+ * @return {?number} Resolved heading level, or `undefined` when the block has none.
+ */
+function getHeadingLevel( blockName, levelAttribute, contextLevel ) {
+	const contextOwned = CONTEXT_HEADING_LEVEL_BLOCKS[ blockName ];
+	if ( ! contextOwned ) {
+		return levelAttribute;
+	}
+	// Mirrors the block's own chain (Accordion Heading saves `h${ level || 3 }`),
+	// so `0` coerces to the fallback instead of reading as a level-0 state.
+	return levelAttribute || contextLevel || contextOwned.fallbackLevel;
+}
+
+/**
+ * Reads the heading level a parent supplies through block context.
+ *
+ * Only the blocks in `CONTEXT_HEADING_LEVEL_BLOCKS` read a key: the value
+ * reaches every descendant, so an ordinary Heading inside an Accordion Panel
+ * must not pick it up. Returns a primitive so callers can use it as a
+ * `useSelect` dependency.
+ *
+ * @param {?string} blockName Block name.
+ * @return {?number} Level from block context, or `undefined`.
+ */
+function useContextHeadingLevel( blockName ) {
+	const blockContext = useContext( BlockContext );
+	const contextKey = CONTEXT_HEADING_LEVEL_BLOCKS[ blockName ]?.contextKey;
+	return contextKey ? blockContext[ contextKey ] : undefined;
+}
+
+/**
+ * Maps a block to the root-level Global Styles *element* layers that paint it
+ * on the canvas, in addition to (or instead of) the block's own class — e.g. a
+ * Button renders `.wp-element-button`, a level-2 Heading renders `<h2>`.
+ *
+ * Keys are ordered low to high precedence, so a level-specific `h2` wins over
+ * the generic `heading`. A level of `0` (e.g. a Site or Post Title rendered as
+ * a paragraph) renders no heading tag, so no element layer applies.
+ *
+ * Hand-maintained by necessity: the block-to-element relationship is not
+ * inferable from block metadata. `supports.color.link` and friends mark blocks
+ * that *contain* an element, not blocks that *are* one, and only the inverse
+ * element-to-selector map exists (`__EXPERIMENTAL_ELEMENTS`). Standardizing it
+ * as a block property is tracked in
+ * https://github.com/WordPress/gutenberg/issues/80438.
+ *
+ * Only blocks that *are* a link fold the `link` layer (e.g. Read More, Login/out
+ * and the pagination links render `<a>` as their whole selves). Blocks that
+ * merely *contain* a link — the heading family, Paragraph, Group, and the
+ * hybrid blocks with a Link colour control (Post Author Name, Post Date, …) —
+ * get no `link` layer: their inner-link control reads the
+ * `inheritedValue.elements.link` passthrough instead, so folding `link` in would
+ * bleed link color into the block's own text.
+ *
+ * @param {string}  blockName    Block name.
+ * @param {?number} headingLevel Resolved heading level, from `getHeadingLevel`.
+ * @return {string[]} Ordered element keys, low to high precedence.
+ */
+function getElementLayers( blockName, headingLevel ) {
+	switch ( blockName ) {
+		case 'core/button':
+			return [ 'button' ];
+		case 'core/accordion-heading':
+		case 'core/heading':
+		case 'core/post-title':
+		case 'core/site-title':
+		case 'core/query-title':
+		case 'core/comments-title':
+		case 'core/term-name':
+		case 'core/site-tagline':
+			if ( headingLevel === 0 ) {
+				return [];
+			}
+			return headingLevel
+				? [ 'heading', `h${ headingLevel }` ]
+				: [ 'heading' ];
+		// Whole-block link blocks: the entire block renders as an `<a>`, so the
+		// root `styles.elements.link` layer paints it, mirroring how `button`
+		// paints Button. For the blocks whose `color.text` support is disabled
+		// this is inert at the (hidden) text control while their typography
+		// controls now reflect the link element; Read More (`color.text: true`)
+		// surfaces the inherited link color at its Text control.
+		case 'core/read-more':
+		case 'core/loginout':
+		case 'core/post-navigation-link':
+		case 'core/query-pagination-next':
+		case 'core/query-pagination-previous':
+		case 'core/query-pagination-numbers':
+		case 'core/comments-pagination-next':
+		case 'core/comments-pagination-previous':
+		case 'core/comments-pagination-numbers':
+		case 'core/comment-edit-link':
+		case 'core/comment-reply-link':
+		case 'core/post-comments-link':
+			return [ 'link' ];
+		default:
+			return [];
+	}
+}
+
+/**
+ * Internal hook that derives the active block-style-variation slug from a
+ * block's `className` by matching registered styles via
+ * `getVariationNameFromClass`, together with the element layers that paint
+ * the block. Both come from a single store subscription.
+ *
+ * The lookup is scoped to a single `useSelect` subscription; the
+ * `@wordpress/blocks` registered-styles slice changes only when a block's
+ * styles are (un)registered, so this subscription is cold in steady-state
+ * editor use.
+ *
+ * The block's `clientId` comes from the block edit context rather than an
+ * argument: these panels always render inside `BlockEditContextProvider`, so
+ * the caller does not have to thread it through.
+ *
+ * @param {?string} blockName Block name (e.g. `core/heading`).
+ * @param {?string} className Space-separated class string from block attributes.
+ * @return {{ variationName: ?string, headingLevel: ?number }} Variation slug
+ * (without the `is-style-` prefix) and the block's heading level, if any.
+ */
+function useVariationAndElements( blockName, className ) {
+	const { clientId } = useBlockEditContext();
+	const contextHeadingLevel = useContextHeadingLevel( blockName );
+	return useSelect(
+		( select ) => {
+			if ( ! blockName ) {
+				return { variationName: null, headingLevel: undefined };
+			}
+			const registeredStyles =
+				select( blocksStore ).getBlockStyles( blockName );
+			const { level } =
+				select( blockEditorStore ).getBlockAttributes( clientId ) || {};
+			// Primitives only: `useSelect` shallow-compares this object, so
+			// returning a fresh array here would re-render on every action.
+			return {
+				variationName: className
+					? getVariationNameFromClass( className, registeredStyles )
+					: null,
+				headingLevel: getHeadingLevel(
+					blockName,
+					level,
+					contextHeadingLevel
+				),
+			};
+		},
+		[ blockName, className, clientId, contextHeadingLevel ]
+	);
+}
+
+/**
+ * Hook: computes the merged, cascade-resolved `inheritedValue` payload and
+ * source map for a selected block, ready to hand to a shared Global Styles
+ * panel via props.
+ *
+ * It reads the merged Global Styles payload and the block's applied variation,
+ * then folds the Root ‹ Block-type ‹ applied-variation cascade (resolving
+ * `{ ref }` envelopes and theme-file pointers) via the pure `resolveStyle`
+ * resolver in `@wordpress/global-styles-engine`. All store access lives here;
+ * the panels stay presentational.
+ *
+ * Before the `globalStylesDataKey` payload settles (hydration) or when
+ * `blockName` is missing, the hook returns empty value and source objects, so
+ * each panel's `inheritedValue = value` default preserves pre-feature behavior.
+ *
+ * @param {?string} blockName       Selected block name (e.g. `core/heading`).
+ * @param {?string} className       Block `className` used to detect an applied variation.
+ * @param {?Object} [selectedState] Selected block style state (`{ viewport, pseudo }`), or null for the default state.
+ * @return {{ value: Object, sources: Object }} Merged panel-scoped payload and source map.
+ */
+export function useResolvedStyle( blockName, className, selectedState = null ) {
+	const { variationName, headingLevel } = useVariationAndElements(
+		blockName,
+		className
+	);
+	const globalStyles = useRawGlobalStyles();
+
+	return useMemo( () => {
+		// Skip the cascade merge entirely when the experiment is off.
+		if ( ! isGlobalStylesInheritanceEnabled() ) {
+			return NO_RESOLVED_STYLE;
+		}
+		if ( ! blockName ) {
+			return { value: {}, sources: {} };
+		}
+		return resolveStyle( globalStyles, {
+			blockName,
+			variationName,
+			elements: getElementLayers( blockName, headingLevel ),
+			viewport: selectedState?.viewport ?? null,
+			pseudoState: selectedState?.pseudo ?? null,
+		} );
+	}, [
+		blockName,
+		variationName,
+		headingLevel,
+		globalStyles,
+		selectedState,
+	] );
+}

package/src/components/global-styles/shadow-panel-components.js

@@ -1,6 +1,3 @@
-/**
- * WordPress dependencies
- */
 import { __ } from '@wordpress/i18n';
 import {
 	__experimentalVStack as VStack,
@@ -14,13 +11,9 @@ import {
 } from '@wordpress/components';
 import { useMemo, useRef } from '@wordpress/element';
 import { shadow as shadowIcon, Icon, check, reset } from '@wordpress/icons';
-
-/**
- * External dependencies
- */
 import clsx from 'clsx';
-
 import { Tooltip } from '@wordpress/ui';
+import { InheritanceResetButton } from './inheritance';
 
 /**
  * Shared reference to an empty array for cases where it is important to avoid
@@ -119,7 +112,15 @@ export function ShadowIndicator( { type, label, isActive, onSelect, shadow } ) {
 	);
 }
 
-export function ShadowPopover( { shadow, onShadowChange, settings } ) {
+export function ShadowPopover( {
+	shadow,
+	onShadowChange,
+	settings,
+	className,
+	hasLocalValue = !! shadow,
+	hasLocalOverride = false,
+	onReset,
+} ) {
 	const popoverProps = {
 		placement: 'left-start',
 		offset: 36,
@@ -129,8 +130,15 @@ export function ShadowPopover( { shadow, onShadowChange, settings } ) {
 	return (
 		<Dropdown
 			popoverProps={ popoverProps }
-			className="block-editor-global-styles__shadow-dropdown"
-			renderToggle={ renderShadowToggle( shadow, onShadowChange ) }
+			className={ clsx(
+				'block-editor-global-styles__shadow-dropdown',
+				className
+			) }
+			renderToggle={ renderShadowToggle( shadow, onShadowChange, {
+				hasLocalValue,
+				hasLocalOverride,
+				onReset: onReset ?? ( () => onShadowChange( undefined ) ),
+			} ) }
 			renderContent={ () => (
 				<DropdownContentWrapper paddingSize="medium">
 					<ShadowPopoverContainer
@@ -144,7 +152,8 @@ export function ShadowPopover( { shadow, onShadowChange, settings } ) {
 	);
 }
 
-function renderShadowToggle( shadow, onShadowChange ) {
+function renderShadowToggle( shadow, onShadowChange, resetConfig ) {
+	const { hasLocalValue, hasLocalOverride, onReset } = resetConfig;
 	return function ShadowToggle( { onToggle, isOpen } ) {
 		const shadowButtonRef = useRef( undefined );
 
@@ -158,20 +167,13 @@ function renderShadowToggle( shadow, onShadowChange ) {
 			ref: shadowButtonRef,
 		};
 
-		const removeButtonProps = {
-			onClick: () => {
-				if ( isOpen ) {
-					onToggle();
-				}
-				onShadowChange( undefined );
-				// Return focus to parent button.
-				shadowButtonRef.current?.focus();
-			},
-			className: clsx(
-				'block-editor-global-styles__shadow-editor__remove-button',
-				{ 'is-open': isOpen }
-			),
-			label: __( 'Remove' ),
+		const handleReset = () => {
+			if ( isOpen ) {
+				onToggle();
+			}
+			onReset();
+			// Return focus to parent button.
+			shadowButtonRef.current?.focus();
 		};
 
 		return (
@@ -186,14 +188,22 @@ function renderShadowToggle( shadow, onShadowChange ) {
 						<FlexItem>{ __( 'Drop shadow' ) }</FlexItem>
 					</HStack>
 				</Button>
-				{ !! shadow && (
-					<Button
-						__next40pxDefaultSize
-						size="small"
-						icon={ reset }
-						{ ...removeButtonProps }
-					/>
-				) }
+				{ hasLocalValue &&
+					( hasLocalOverride ? (
+						<InheritanceResetButton
+							className="block-editor-global-styles__shadow-editor__remove-button"
+							onResetToInherited={ handleReset }
+						/>
+					) : (
+						<Button
+							__next40pxDefaultSize
+							size="small"
+							icon={ reset }
+							label={ __( 'Remove' ) }
+							className="block-editor-global-styles__shadow-editor__remove-button"
+							onClick={ handleReset }
+						/>
+					) ) }
 			</>
 		);
 	};