@wordpress/block-editor 11.1.0 → 11.2.0

package/src/hooks/position.js

@@ -0,0 +1,375 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { __, sprintf } from '@wordpress/i18n';
+import { getBlockSupport, hasBlockSupport } from '@wordpress/blocks';
+import { BaseControl, CustomSelectControl } from '@wordpress/components';
+import { createHigherOrderComponent, useInstanceId } from '@wordpress/compose';
+import {
+	useContext,
+	useMemo,
+	createPortal,
+	Platform,
+} from '@wordpress/element';
+import { addFilter } from '@wordpress/hooks';
+
+/**
+ * Internal dependencies
+ */
+import BlockList from '../components/block-list';
+import useSetting from '../components/use-setting';
+import InspectorControls from '../components/inspector-controls';
+import { cleanEmptyObject } from './utils';
+
+const POSITION_SUPPORT_KEY = 'position';
+
+const OPTION_CLASSNAME =
+	'block-editor-hooks__position-selection__select-control__option';
+
+const DEFAULT_OPTION = {
+	key: 'default',
+	value: '',
+	name: __( 'Default' ),
+	className: OPTION_CLASSNAME,
+};
+
+const STICKY_OPTION = {
+	key: 'sticky',
+	value: 'sticky',
+	name: __( 'Sticky' ),
+	className: OPTION_CLASSNAME,
+	__experimentalHint: __(
+		'The block will stick to the top of the window instead of scrolling.'
+	),
+};
+
+const FIXED_OPTION = {
+	key: 'fixed',
+	value: 'fixed',
+	name: __( 'Fixed' ),
+	className: OPTION_CLASSNAME,
+	__experimentalHint: __(
+		'The block will not move when the page is scrolled.'
+	),
+};
+
+const POSITION_SIDES = [ 'top', 'right', 'bottom', 'left' ];
+const VALID_POSITION_TYPES = [ 'sticky', 'fixed' ];
+
+/**
+ * Get calculated position CSS.
+ *
+ * @param {Object} props          Component props.
+ * @param {string} props.selector Selector to use.
+ * @param {Object} props.style    Style object.
+ * @return {string} The generated CSS rules.
+ */
+export function getPositionCSS( { selector, style } ) {
+	let output = '';
+
+	const { type: positionType } = style?.position || {};
+
+	if ( ! VALID_POSITION_TYPES.includes( positionType ) ) {
+		return output;
+	}
+
+	output += `${ selector } {`;
+	output += `position: ${ positionType };`;
+
+	POSITION_SIDES.forEach( ( side ) => {
+		if ( style?.position?.[ side ] !== undefined ) {
+			output += `${ side }: ${ style.position[ side ] };`;
+		}
+	} );
+
+	if ( positionType === 'sticky' || positionType === 'fixed' ) {
+		// TODO: Replace hard-coded z-index value with a z-index preset approach in theme.json.
+		output += `z-index: 10`;
+	}
+	output += `}`;
+
+	return output;
+}
+
+/**
+ * Determines if there is sticky position support.
+ *
+ * @param {string|Object} blockType Block name or Block Type object.
+ *
+ * @return {boolean} Whether there is support.
+ */
+export function hasStickyPositionSupport( blockType ) {
+	const support = getBlockSupport( blockType, POSITION_SUPPORT_KEY );
+	return !! ( true === support || support?.sticky );
+}
+
+/**
+ * Determines if there is fixed position support.
+ *
+ * @param {string|Object} blockType Block name or Block Type object.
+ *
+ * @return {boolean} Whether there is support.
+ */
+export function hasFixedPositionSupport( blockType ) {
+	const support = getBlockSupport( blockType, POSITION_SUPPORT_KEY );
+	return !! ( true === support || support?.fixed );
+}
+
+/**
+ * Determines if there is position support.
+ *
+ * @param {string|Object} blockType Block name or Block Type object.
+ *
+ * @return {boolean} Whether there is support.
+ */
+export function hasPositionSupport( blockType ) {
+	const support = getBlockSupport( blockType, POSITION_SUPPORT_KEY );
+	return !! support;
+}
+
+/**
+ * Checks if there is a current value in the position block support attributes.
+ *
+ * @param {Object} props Block props.
+ * @return {boolean} Whether or not the block has a position value set.
+ */
+export function hasPositionValue( props ) {
+	return props.attributes.style?.position?.type !== undefined;
+}
+
+/**
+ * Checks if the block is currently set to a sticky or fixed position.
+ * This check is helpful for determining how to position block toolbars or other elements.
+ *
+ * @param {Object} attributes Block attributes.
+ * @return {boolean} Whether or not the block is set to a sticky or fixed position.
+ */
+export function hasStickyOrFixedPositionValue( attributes ) {
+	const positionType = attributes.style?.position?.type;
+	return positionType === 'sticky' || positionType === 'fixed';
+}
+
+/**
+ * Resets the position block support attributes. This can be used when disabling
+ * the position support controls for a block via a `ToolsPanel`.
+ *
+ * @param {Object} props               Block props.
+ * @param {Object} props.attributes    Block's attributes.
+ * @param {Object} props.setAttributes Function to set block's attributes.
+ */
+export function resetPosition( { attributes = {}, setAttributes } ) {
+	const { style = {} } = attributes;
+
+	setAttributes( {
+		style: cleanEmptyObject( {
+			...style,
+			position: {
+				...style?.position,
+				type: undefined,
+				top: undefined,
+				right: undefined,
+				bottom: undefined,
+				left: undefined,
+			},
+		} ),
+	} );
+}
+
+/**
+ * Custom hook that checks if position settings have been disabled.
+ *
+ * @param {string} name The name of the block.
+ *
+ * @return {boolean} Whether padding setting is disabled.
+ */
+export function useIsPositionDisabled( { name: blockName } = {} ) {
+	const allowFixed = useSetting( 'position.fixed' );
+	const allowSticky = useSetting( 'position.sticky' );
+	const isDisabled = ! allowFixed && ! allowSticky;
+
+	return ! hasPositionSupport( blockName ) || isDisabled;
+}
+
+/*
+ * Position controls to be rendered in an inspector control panel.
+ *
+ * @param {Object} props
+ *
+ * @return {WPElement} Padding edit element.
+ */
+export function PositionEdit( props ) {
+	const {
+		attributes: { style = {} },
+		name: blockName,
+		setAttributes,
+	} = props;
+
+	const allowFixed = hasFixedPositionSupport( blockName );
+	const allowSticky = hasStickyPositionSupport( blockName );
+	const value = style?.position?.type;
+
+	const options = useMemo( () => {
+		const availableOptions = [ DEFAULT_OPTION ];
+		if ( allowSticky || value === STICKY_OPTION.value ) {
+			availableOptions.push( STICKY_OPTION );
+		}
+		if ( allowFixed || value === FIXED_OPTION.value ) {
+			availableOptions.push( FIXED_OPTION );
+		}
+		return availableOptions;
+	}, [ allowFixed, allowSticky, value ] );
+
+	const onChangeType = ( next ) => {
+		// For now, use a hard-coded `0px` value for the position.
+		// `0px` is preferred over `0` as it can be used in `calc()` functions.
+		// In the future, it could be useful to allow for an offset value.
+		const placementValue = '0px';
+
+		const newStyle = {
+			...style,
+			position: {
+				...style?.position,
+				type: next,
+				top:
+					next === 'sticky' || next === 'fixed'
+						? placementValue
+						: undefined,
+			},
+		};
+
+		setAttributes( {
+			style: cleanEmptyObject( newStyle ),
+		} );
+	};
+
+	const selectedOption = value
+		? options.find( ( option ) => option.value === value ) || DEFAULT_OPTION
+		: DEFAULT_OPTION;
+
+	return Platform.select( {
+		web: (
+			<>
+				<BaseControl className="block-editor-hooks__position-selection">
+					<CustomSelectControl
+						__nextUnconstrainedWidth
+						__next36pxDefaultSize
+						className="block-editor-hooks__position-selection__select-control"
+						label={ __( 'Position' ) }
+						hideLabelFromVision
+						describedBy={ sprintf(
+							// translators: %s: Currently selected font size.
+							__( 'Currently selected position: %s' ),
+							selectedOption.name
+						) }
+						options={ options }
+						value={ selectedOption }
+						__experimentalShowSelectedHint
+						onChange={ ( { selectedItem } ) => {
+							onChangeType( selectedItem.value );
+						} }
+						size={ '__unstable-large' }
+					/>
+				</BaseControl>
+			</>
+		),
+		native: null,
+	} );
+}
+
+/**
+ * Override the default edit UI to include position controls.
+ *
+ * @param {Function} BlockEdit Original component.
+ *
+ * @return {Function} Wrapped component.
+ */
+export const withInspectorControls = createHigherOrderComponent(
+	( BlockEdit ) => ( props ) => {
+		const { name: blockName } = props;
+		const positionSupport = hasBlockSupport(
+			blockName,
+			POSITION_SUPPORT_KEY
+		);
+		const showPositionControls =
+			positionSupport && ! useIsPositionDisabled( props );
+
+		return [
+			showPositionControls && (
+				<InspectorControls
+					key="position"
+					__experimentalGroup="position"
+				>
+					<PositionEdit { ...props } />
+				</InspectorControls>
+			),
+			<BlockEdit key="edit" { ...props } />,
+		];
+	},
+	'withInspectorControls'
+);
+
+/**
+ * Override the default block element to add the position styles.
+ *
+ * @param {Function} BlockListBlock Original component.
+ *
+ * @return {Function} Wrapped component.
+ */
+export const withPositionStyles = createHigherOrderComponent(
+	( BlockListBlock ) => ( props ) => {
+		const { name, attributes } = props;
+		const hasPositionBlockSupport = hasBlockSupport(
+			name,
+			POSITION_SUPPORT_KEY
+		);
+		const allowPositionStyles =
+			hasPositionBlockSupport && ! useIsPositionDisabled( props );
+
+		const id = useInstanceId( BlockListBlock );
+		const element = useContext( BlockList.__unstableElementContext );
+
+		// Higher specificity to override defaults in editor UI.
+		const positionSelector = `.wp-container-${ id }.wp-container-${ id }`;
+
+		// Get CSS string for the current position values.
+		let css;
+		if ( allowPositionStyles ) {
+			css =
+				getPositionCSS( {
+					selector: positionSelector,
+					style: attributes?.style,
+				} ) || '';
+		}
+
+		// Attach a `wp-container-` id-based class name.
+		const className = classnames( props?.className, {
+			[ `wp-container-${ id }` ]: allowPositionStyles && !! css, // Only attach a container class if there is generated CSS to be attached.
+		} );
+
+		return (
+			<>
+				{ allowPositionStyles &&
+					element &&
+					!! css &&
+					createPortal( <style>{ css }</style>, element ) }
+				<BlockListBlock { ...props } className={ className } />
+			</>
+		);
+	}
+);
+
+addFilter(
+	'editor.BlockListBlock',
+	'core/editor/position/with-position-styles',
+	withPositionStyles
+);
+addFilter(
+	'editor.BlockEdit',
+	'core/editor/position/with-inspector-controls',
+	withInspectorControls
+);

package/src/hooks/position.scss

@@ -0,0 +1,18 @@
+.block-editor-hooks__position-selection__select-control {
+	.components-custom-select-control__hint {
+		display: none;
+	}
+}
+
+.block-editor-hooks__position-selection__select-control__option {
+	&.has-hint {
+		grid-template-columns: auto 30px;
+		line-height: $default-line-height;
+		margin-bottom: 0;
+	}
+
+	.components-custom-select-control__item-hint {
+		grid-row: 2;
+		text-align: left;
+	}
+}

package/src/hooks/supports.js

@@ -0,0 +1,302 @@
+/**
+ * WordPress dependencies
+ */
+import { getBlockSupport, hasBlockSupport } from '@wordpress/blocks';
+import { Platform } from '@wordpress/element';
+
+const ALIGN_SUPPORT_KEY = 'align';
+const ALIGN_WIDE_SUPPORT_KEY = 'alignWide';
+const BORDER_SUPPORT_KEY = '__experimentalBorder';
+const COLOR_SUPPORT_KEY = 'color';
+const CUSTOM_CLASS_NAME_SUPPORT_KEY = 'customClassName';
+const FONT_FAMILY_SUPPORT_KEY = 'typography.__experimentalFontFamily';
+const FONT_SIZE_SUPPORT_KEY = 'typography.fontSize';
+const LINE_HEIGHT_SUPPORT_KEY = 'typography.lineHeight';
+/**
+ * Key within block settings' support array indicating support for font style.
+ */
+const FONT_STYLE_SUPPORT_KEY = 'typography.__experimentalFontStyle';
+/**
+ * Key within block settings' support array indicating support for font weight.
+ */
+const FONT_WEIGHT_SUPPORT_KEY = 'typography.__experimentalFontWeight';
+/**
+ * Key within block settings' supports array indicating support for text
+ * decorations e.g. settings found in `block.json`.
+ */
+const TEXT_DECORATION_SUPPORT_KEY = 'typography.__experimentalTextDecoration';
+/**
+ * Key within block settings' supports array indicating support for text
+ * transforms e.g. settings found in `block.json`.
+ */
+const TEXT_TRANSFORM_SUPPORT_KEY = 'typography.__experimentalTextTransform';
+/**
+ * Key within block settings' supports array indicating support for letter-spacing
+ * e.g. settings found in `block.json`.
+ */
+const LETTER_SPACING_SUPPORT_KEY = 'typography.__experimentalLetterSpacing';
+const LAYOUT_SUPPORT_KEY = '__experimentalLayout';
+const TYPOGRAPHY_SUPPORT_KEYS = [
+	LINE_HEIGHT_SUPPORT_KEY,
+	FONT_SIZE_SUPPORT_KEY,
+	FONT_STYLE_SUPPORT_KEY,
+	FONT_WEIGHT_SUPPORT_KEY,
+	FONT_FAMILY_SUPPORT_KEY,
+	TEXT_DECORATION_SUPPORT_KEY,
+	TEXT_TRANSFORM_SUPPORT_KEY,
+	LETTER_SPACING_SUPPORT_KEY,
+];
+const SPACING_SUPPORT_KEY = 'spacing';
+const styleSupportKeys = [
+	...TYPOGRAPHY_SUPPORT_KEYS,
+	BORDER_SUPPORT_KEY,
+	COLOR_SUPPORT_KEY,
+	SPACING_SUPPORT_KEY,
+];
+
+/**
+ * Returns true if the block defines support for align.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasAlignSupport = ( nameOrType ) =>
+	hasBlockSupport( nameOrType, ALIGN_SUPPORT_KEY );
+
+/**
+ * Returns the block support value for align, if defined.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {unknown} The block support value.
+ */
+export const getAlignSupport = ( nameOrType ) =>
+	getBlockSupport( nameOrType, ALIGN_SUPPORT_KEY );
+
+/**
+ * Returns true if the block defines support for align wide.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasAlignWideSupport = ( nameOrType ) =>
+	hasBlockSupport( nameOrType, ALIGN_WIDE_SUPPORT_KEY );
+
+/**
+ * Returns the block support value for align wide, if defined.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {unknown} The block support value.
+ */
+export const getAlignWideSupport = ( nameOrType ) =>
+	getBlockSupport( nameOrType, ALIGN_WIDE_SUPPORT_KEY );
+
+/**
+ * Determine whether there is block support for border properties.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @param {string}        feature    Border feature to check support for.
+ *
+ * @return {boolean} Whether there is support.
+ */
+export function hasBorderSupport( nameOrType, feature = 'any' ) {
+	if ( Platform.OS !== 'web' ) {
+		return false;
+	}
+
+	const support = getBlockSupport( nameOrType, BORDER_SUPPORT_KEY );
+
+	if ( support === true ) {
+		return true;
+	}
+
+	if ( feature === 'any' ) {
+		return !! (
+			support?.color ||
+			support?.radius ||
+			support?.width ||
+			support?.style
+		);
+	}
+
+	return !! support?.[ feature ];
+}
+
+/**
+ * Get block support for border properties.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @param {string}        feature    Border feature to get.
+ *
+ * @return {unknown} The block support.
+ */
+export const getBorderSupport = ( nameOrType, feature ) =>
+	getBlockSupport( nameOrType, [ BORDER_SUPPORT_KEY, feature ] );
+
+/**
+ * Returns true if the block defines support for color.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasColorSupport = ( nameOrType ) => {
+	const colorSupport = getBlockSupport( nameOrType, COLOR_SUPPORT_KEY );
+	return (
+		colorSupport &&
+		( colorSupport.link === true ||
+			colorSupport.gradient === true ||
+			colorSupport.background !== false ||
+			colorSupport.text !== false )
+	);
+};
+
+/**
+ * Returns true if the block defines support for link color.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasLinkColorSupport = ( nameOrType ) => {
+	if ( Platform.OS !== 'web' ) {
+		return false;
+	}
+
+	const colorSupport = getBlockSupport( nameOrType, COLOR_SUPPORT_KEY );
+
+	return (
+		colorSupport !== null &&
+		typeof colorSupport === 'object' &&
+		!! colorSupport.link
+	);
+};
+
+/**
+ * Returns true if the block defines support for gradient color.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasGradientSupport = ( nameOrType ) => {
+	const colorSupport = getBlockSupport( nameOrType, COLOR_SUPPORT_KEY );
+
+	return (
+		colorSupport !== null &&
+		typeof colorSupport === 'object' &&
+		!! colorSupport.gradients
+	);
+};
+
+/**
+ * Returns true if the block defines support for background color.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasBackgroundColorSupport = ( nameOrType ) => {
+	const colorSupport = getBlockSupport( nameOrType, COLOR_SUPPORT_KEY );
+
+	return colorSupport && colorSupport.background !== false;
+};
+
+/**
+ * Returns true if the block defines support for background color.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasTextColorSupport = ( nameOrType ) => {
+	const colorSupport = getBlockSupport( nameOrType, COLOR_SUPPORT_KEY );
+
+	return colorSupport && colorSupport.text !== false;
+};
+
+/**
+ * Get block support for color properties.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @param {string}        feature    Color feature to get.
+ *
+ * @return {unknown} The block support.
+ */
+export const getColorSupport = ( nameOrType, feature ) =>
+	getBlockSupport( nameOrType, [ COLOR_SUPPORT_KEY, feature ] );
+
+/**
+ * Returns true if the block defines support for custom class name.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasCustomClassNameSupport = ( nameOrType ) =>
+	hasBlockSupport( nameOrType, CUSTOM_CLASS_NAME_SUPPORT_KEY, true );
+
+/**
+ * Returns the block support value for custom class name, if defined.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {unknown} The block support value.
+ */
+export const getCustomClassNameSupport = ( nameOrType ) =>
+	getBlockSupport( nameOrType, CUSTOM_CLASS_NAME_SUPPORT_KEY, true );
+
+/**
+ * Returns true if the block defines support for font family.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasFontFamilySupport = ( nameOrType ) =>
+	hasBlockSupport( nameOrType, FONT_FAMILY_SUPPORT_KEY );
+
+/**
+ * Returns the block support value for font family, if defined.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {unknown} The block support value.
+ */
+export const getFontFamilySupport = ( nameOrType ) =>
+	getBlockSupport( nameOrType, FONT_FAMILY_SUPPORT_KEY );
+
+/**
+ * Returns true if the block defines support for font size.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasFontSizeSupport = ( nameOrType ) =>
+	hasBlockSupport( nameOrType, FONT_SIZE_SUPPORT_KEY );
+
+/**
+ * Returns the block support value for font size, if defined.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {unknown} The block support value.
+ */
+export const getFontSizeSupport = ( nameOrType ) =>
+	getBlockSupport( nameOrType, FONT_SIZE_SUPPORT_KEY );
+
+/**
+ * Returns true if the block defines support for layout.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasLayoutSupport = ( nameOrType ) =>
+	hasBlockSupport( nameOrType, LAYOUT_SUPPORT_KEY );
+
+/**
+ * Returns the block support value for layout, if defined.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {unknown} The block support value.
+ */
+export const getLayoutSupport = ( nameOrType ) =>
+	getBlockSupport( nameOrType, LAYOUT_SUPPORT_KEY );
+
+/**
+ * Returns true if the block defines support for style.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasStyleSupport = ( nameOrType ) =>
+	styleSupportKeys.some( ( key ) => hasBlockSupport( nameOrType, key ) );