@wordpress/components 29.0.0 → 29.1.0

package/src/box-control/input-control.tsx

@@ -3,6 +3,8 @@
  */
 import { useInstanceId } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
+import { useState } from '@wordpress/element';
+import { settings } from '@wordpress/icons';
 
 /**
  * Internal dependencies
@@ -11,10 +13,13 @@ import Tooltip from '../tooltip';
 import { parseQuantityAndUnitFromRawValue } from '../unit-control/utils';
 import {
 	CUSTOM_VALUE_SETTINGS,
-	getAllowedSides,
 	getMergedValue,
-	isValueMixed,
+	getAllowedSides,
+	getPresetIndexFromValue,
+	getPresetValueFromIndex,
+	isValuePreset,
 	isValuesDefined,
+	isValueMixed,
 	LABELS,
 } from './utils';
 import {
@@ -24,6 +29,7 @@ import {
 	StyledUnitControl,
 } from './styles/box-control-styles';
 import type { BoxControlInputControlProps, BoxControlValue } from './types';
+import Button from '../button';
 
 const noop = () => {};
 
@@ -78,6 +84,9 @@ export default function BoxInputControl( {
 	setSelectedUnits,
 	sides,
 	side,
+	min = 0,
+	presets,
+	presetKey,
 	...props
 }: BoxControlInputControlProps ) {
 	const defaultValuesToModify = getSidesToModify( side, sides );
@@ -90,6 +99,15 @@ export default function BoxInputControl( {
 		onChange( nextValues );
 	};
 
+	const handleRawOnValueChange = ( next?: string ) => {
+		const nextValues = { ...values };
+		defaultValuesToModify.forEach( ( modifiedSide ) => {
+			nextValues[ modifiedSide ] = next;
+		} );
+
+		handleOnChange( nextValues );
+	};
+
 	const handleOnValueChange = (
 		next?: string,
 		extra?: { event: React.SyntheticEvent< Element, Event > }
@@ -147,51 +165,135 @@ export default function BoxInputControl( {
 	const usedValue =
 		mergedValue === undefined && computedUnit ? computedUnit : mergedValue;
 	const mixedPlaceholder = isMixed || isMixedUnit ? __( 'Mixed' ) : undefined;
+	const hasPresets = presets && presets.length > 0 && presetKey;
+	const hasPresetValue =
+		hasPresets &&
+		mergedValue !== undefined &&
+		! isMixed &&
+		isValuePreset( mergedValue, presetKey );
+	const [ showCustomValueControl, setShowCustomValueControl ] = useState(
+		! hasPresets ||
+			( ! hasPresetValue && ! isMixed && mergedValue !== undefined )
+	);
+	const presetIndex = hasPresetValue
+		? getPresetIndexFromValue( mergedValue, presetKey, presets )
+		: undefined;
+	const marks = hasPresets
+		? [ { value: 0, label: '', tooltip: __( 'None' ) } ].concat(
+				presets.map( ( preset, index ) => ( {
+					value: index + 1,
+					label: '',
+					tooltip: preset.name ?? preset.slug,
+				} ) )
+		  )
+		: [];
 
 	return (
 		<InputWrapper key={ `box-control-${ side }` } expanded>
 			<FlexedBoxControlIcon side={ side } sides={ sides } />
-			<Tooltip placement="top-end" text={ LABELS[ side ] }>
-				<StyledUnitControl
-					{ ...props }
-					__shouldNotWarnDeprecated36pxSize
-					__next40pxDefaultSize={ __next40pxDefaultSize }
-					className="component-box-control__unit-control"
-					id={ inputId }
-					isPressEnterToChange
-					disableUnits={ isMixed || isMixedUnit }
-					value={ usedValue }
-					onChange={ handleOnValueChange }
-					onUnitChange={ handleOnUnitChange }
-					onFocus={ handleOnFocus }
+			{ showCustomValueControl && (
+				<>
+					<Tooltip placement="top-end" text={ LABELS[ side ] }>
+						<StyledUnitControl
+							{ ...props }
+							min={ min }
+							__shouldNotWarnDeprecated36pxSize
+							__next40pxDefaultSize={ __next40pxDefaultSize }
+							className="component-box-control__unit-control"
+							id={ inputId }
+							isPressEnterToChange
+							disableUnits={ isMixed || isMixedUnit }
+							value={ usedValue }
+							onChange={ handleOnValueChange }
+							onUnitChange={ handleOnUnitChange }
+							onFocus={ handleOnFocus }
+							label={ LABELS[ side ] }
+							placeholder={ mixedPlaceholder }
+							hideLabelFromVision
+						/>
+					</Tooltip>
+
+					<FlexedRangeControl
+						__nextHasNoMarginBottom
+						__next40pxDefaultSize={ __next40pxDefaultSize }
+						__shouldNotWarnDeprecated36pxSize
+						aria-controls={ inputId }
+						label={ LABELS[ side ] }
+						hideLabelFromVision
+						onChange={ ( newValue ) => {
+							handleOnValueChange(
+								newValue !== undefined
+									? [ newValue, computedUnit ].join( '' )
+									: undefined
+							);
+						} }
+						min={ isFinite( min ) ? min : 0 }
+						max={
+							CUSTOM_VALUE_SETTINGS[ computedUnit ?? 'px' ]
+								?.max ?? 10
+						}
+						step={
+							CUSTOM_VALUE_SETTINGS[ computedUnit ?? 'px' ]
+								?.step ?? 0.1
+						}
+						value={ parsedQuantity ?? 0 }
+						withInputField={ false }
+					/>
+				</>
+			) }
+
+			{ hasPresets && ! showCustomValueControl && (
+				<FlexedRangeControl
+					__next40pxDefaultSize
+					className="spacing-sizes-control__range-control"
+					value={ presetIndex !== undefined ? presetIndex + 1 : 0 }
+					onChange={ ( newIndex ) => {
+						const newValue =
+							newIndex === 0 || newIndex === undefined
+								? undefined
+								: getPresetValueFromIndex(
+										newIndex - 1,
+										presetKey,
+										presets
+								  );
+						handleRawOnValueChange( newValue );
+					} }
+					withInputField={ false }
+					aria-valuenow={
+						presetIndex !== undefined ? presetIndex + 1 : 0
+					}
+					aria-valuetext={
+						marks[ presetIndex !== undefined ? presetIndex + 1 : 0 ]
+							.tooltip
+					}
+					renderTooltipContent={ ( index ) =>
+						marks[ ! index ? 0 : index ].tooltip
+					}
+					min={ 0 }
+					max={ marks.length - 1 }
+					marks={ marks }
 					label={ LABELS[ side ] }
-					placeholder={ mixedPlaceholder }
 					hideLabelFromVision
+					__nextHasNoMarginBottom
+				/>
+			) }
+
+			{ hasPresets && (
+				<Button
+					label={
+						showCustomValueControl
+							? __( 'Use size preset' )
+							: __( 'Set custom size' )
+					}
+					icon={ settings }
+					onClick={ () => {
+						setShowCustomValueControl( ! showCustomValueControl );
+					} }
+					isPressed={ showCustomValueControl }
+					size="small"
+					iconSize={ 24 }
 				/>
-			</Tooltip>
-
-			<FlexedRangeControl
-				__nextHasNoMarginBottom
-				__next40pxDefaultSize={ __next40pxDefaultSize }
-				__shouldNotWarnDeprecated36pxSize
-				aria-controls={ inputId }
-				label={ LABELS[ side ] }
-				hideLabelFromVision
-				onChange={ ( newValue ) => {
-					handleOnValueChange(
-						newValue !== undefined
-							? [ newValue, computedUnit ].join( '' )
-							: undefined
-					);
-				} }
-				min={ 0 }
-				max={ CUSTOM_VALUE_SETTINGS[ computedUnit ?? 'px' ]?.max ?? 10 }
-				step={
-					CUSTOM_VALUE_SETTINGS[ computedUnit ?? 'px' ]?.step ?? 0.1
-				}
-				value={ parsedQuantity ?? 0 }
-				withInputField={ false }
-			/>
+			) }
 		</InputWrapper>
 	);
 }

package/src/box-control/stories/index.story.tsx

@@ -81,3 +81,15 @@ AxialControlsWithSingleSide.args = {
 	sides: [ 'horizontal' ],
 	splitOnAxis: true,
 };
+
+export const ControlWithPresets = TemplateControlled.bind( {} );
+ControlWithPresets.args = {
+	...Default.args,
+	presets: [
+		{ name: 'Small', slug: 'small', value: '4px' },
+		{ name: 'Medium', slug: 'medium', value: '8px' },
+		{ name: 'Large', slug: 'large', value: '12px' },
+		{ name: 'Extra Large', slug: 'extra-large', value: '16px' },
+	],
+	presetKey: 'padding',
+};

package/src/box-control/types.ts

@@ -15,6 +15,12 @@ export type CustomValueUnits = {
 	[ key: string ]: { max: number; step: number };
 };
 
+export interface Preset {
+	name: string;
+	slug: string;
+	value?: string;
+}
+
 type UnitControlPassthroughProps = Omit<
 	UnitControlProps,
 	'label' | 'onChange' | 'onFocus' | 'units'
@@ -94,6 +100,16 @@ export type BoxControlProps = Pick< UnitControlProps, 'units' > &
 		 * @default false
 		 */
 		__next40pxDefaultSize?: boolean;
+		/**
+		 * Available presets to pick from.
+		 */
+		presets?: Preset[];
+		/**
+		 * The key of the preset to apply.
+		 * If you provide a list of presets, you must provide a preset key to use.
+		 * The format of preset selected values is going to be `var:preset|${ presetKey }|${ presetSlug }`
+		 */
+		presetKey?: string;
 	};
 
 export type BoxControlInputControlProps = UnitControlPassthroughProps & {
@@ -120,6 +136,8 @@ export type BoxControlInputControlProps = UnitControlPassthroughProps & {
 	 * It can be a concrete side like: left, right, top, bottom or a combined one like: horizontal, vertical.
 	 */
 	side: keyof typeof LABELS;
+	presets?: Preset[];
+	presetKey?: string;
 };
 
 export type BoxControlIconProps = {

package/src/box-control/utils.ts

@@ -11,6 +11,7 @@ import type {
 	BoxControlProps,
 	BoxControlValue,
 	CustomValueUnits,
+	Preset,
 } from './types';
 import deprecated from '@wordpress/deprecated';
 
@@ -272,3 +273,62 @@ export function getAllowedSides(
 	} );
 	return allowedSides;
 }
+
+/**
+ * Checks if a value is a preset value.
+ *
+ * @param value     The value to check.
+ * @param presetKey The preset key to check against.
+ * @return Whether the value is a preset value.
+ */
+export function isValuePreset( value: string, presetKey: string ) {
+	return value.startsWith( `var:preset|${ presetKey }|` );
+}
+
+/**
+ * Returns the index of the preset value in the presets array.
+ *
+ * @param value     The value to check.
+ * @param presetKey The preset key to check against.
+ * @param presets   The array of presets to search.
+ * @return The index of the preset value in the presets array.
+ */
+export function getPresetIndexFromValue(
+	value: string,
+	presetKey: string,
+	presets: Preset[]
+) {
+	if ( ! isValuePreset( value, presetKey ) ) {
+		return undefined;
+	}
+
+	const match = value.match(
+		new RegExp( `^var:preset\\|${ presetKey }\\|(.+)$` )
+	);
+	if ( ! match ) {
+		return undefined;
+	}
+	const slug = match[ 1 ];
+	const index = presets.findIndex( ( preset ) => {
+		return preset.slug === slug;
+	} );
+
+	return index !== -1 ? index : undefined;
+}
+
+/**
+ * Returns the preset value from the index.
+ *
+ * @param index     The index of the preset value in the presets array.
+ * @param presetKey The preset key to check against.
+ * @param presets   The array of presets to search.
+ * @return The preset value from the index.
+ */
+export function getPresetValueFromIndex(
+	index: number,
+	presetKey: string,
+	presets: Preset[]
+) {
+	const preset = presets[ index ];
+	return `var:preset|${ presetKey }|${ preset.slug }`;
+}

package/src/button/README.md

@@ -17,19 +17,24 @@ const Mybutton = () => (
   </Button>
 );
 ```
+
 ## Props
 
 ### `__next40pxDefaultSize`
 
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
 Start opting into the larger default height that will become the
 default size in a future version.
 
+### `accessibleWhenDisabled`
+
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `accessibleWhenDisabled`
-
 Whether to keep the button focusable when disabled.
 
 In most cases, it is recommended to set this to `true`. Disabling a control without maintaining focusability
@@ -39,111 +44,111 @@ or by preventing focus from returning to a trigger element.
 Learn more about the [focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols)
 in the WAI-ARIA Authoring Practices Guide.
 
- - Type: `boolean`
- - Required: No
- - Default: `false`
-
 ### `children`
 
-The button's children.
-
  - Type: `ReactNode`
  - Required: No
 
-### `description`
+The button's children.
 
-A visually hidden accessible description for the button.
+### `description`
 
  - Type: `string`
  - Required: No
 
+A visually hidden accessible description for the button.
+
 ### `disabled`
 
+ - Type: `boolean`
+ - Required: No
+
 Whether the button is disabled. If `true`, this will force a `button` element
 to be rendered, even when an `href` is given.
 
 In most cases, it is recommended to also set the `accessibleWhenDisabled` prop to `true`.
 
- - Type: `boolean`
- - Required: No
-
 ### `href`
 
-If provided, renders `a` instead of `button`.
-
  - Type: `string`
  - Required: Yes
 
-### `icon`
+If provided, renders `a` instead of `button`.
 
-If provided, renders an Icon component inside the button.
+### `icon`
 
  - Type: `IconType`
  - Required: No
 
-### `iconPosition`
+If provided, renders an Icon component inside the button.
 
-If provided with `icon`, sets the position of icon relative to the `text`.
+### `iconPosition`
 
  - Type: `"left" | "right"`
  - Required: No
  - Default: `'left'`
 
+If provided with `icon`, sets the position of icon relative to the `text`.
+
 ### `iconSize`
 
+ - Type: `number`
+ - Required: No
+
 If provided with `icon`, sets the icon size.
 Please refer to the Icon component for more details regarding
 the default value of its `size` prop.
 
- - Type: `number`
- - Required: No
-
 ### `isBusy`
 
-Indicates activity while a action is being performed.
-
  - Type: `boolean`
  - Required: No
 
-### `isDestructive`
+Indicates activity while a action is being performed.
 
-Renders a red text-based button style to indicate destructive behavior.
+### `isDestructive`
 
  - Type: `boolean`
  - Required: No
 
-### `isPressed`
+Renders a red text-based button style to indicate destructive behavior.
 
-Renders a pressed button style.
+### `isPressed`
 
  - Type: `boolean`
  - Required: No
 
-### `label`
+Renders a pressed button style.
 
-Sets the `aria-label` of the component, if none is provided.
-Sets the Tooltip content if `showTooltip` is provided.
+### `label`
 
  - Type: `string`
  - Required: No
 
-### `shortcut`
+Sets the `aria-label` of the component, if none is provided.
+Sets the Tooltip content if `showTooltip` is provided.
 
-If provided with `showTooltip`, appends the Shortcut label to the tooltip content.
-If an object is provided, it should contain `display` and `ariaLabel` keys.
+### `shortcut`
 
  - Type: `string | { display: string; ariaLabel: string; }`
  - Required: No
 
-### `showTooltip`
+If provided with `showTooltip`, appends the Shortcut label to the tooltip content.
+If an object is provided, it should contain `display` and `ariaLabel` keys.
 
-If provided, renders a Tooltip component for the button.
+### `showTooltip`
 
  - Type: `boolean`
  - Required: No
 
+If provided, renders a Tooltip component for the button.
+
 ### `size`
 
+ - Type: `"small" | "default" | "compact"`
+ - Required: No
+ - Default: `'default'`
+
 The size of the button.
 
 - `'default'`: For normal text-label buttons, unless it is a toggle button.
@@ -152,34 +157,33 @@ The size of the button.
 
 If the deprecated `isSmall` prop is also defined, this prop will take precedence.
 
- - Type: `"small" | "default" | "compact"`
- - Required: No
- - Default: `'default'`
-
 ### `text`
 
-If provided, displays the given text inside the button. If the button contains children elements, the text is displayed before them.
-
  - Type: `string`
  - Required: No
 
-### `tooltipPosition`
+If provided, displays the given text inside the button. If the button contains children elements, the text is displayed before them.
 
-If provided with `showTooltip`, sets the position of the tooltip.
-Please refer to the Tooltip component for more details regarding the defaults.
+### `tooltipPosition`
 
  - Type: `"top" | "middle" | "bottom" | "top center" | "top left" | "top right" | "middle center" | "middle left" | "middle right" | "bottom center" | ...`
  - Required: No
 
-### `target`
+If provided with `showTooltip`, sets the position of the tooltip.
+Please refer to the Tooltip component for more details regarding the defaults.
 
-If provided with `href`, sets the `target` attribute to the `a`.
+### `target`
 
  - Type: `string`
  - Required: No
 
+If provided with `href`, sets the `target` attribute to the `a`.
+
 ### `variant`
 
+ - Type: `"link" | "primary" | "secondary" | "tertiary"`
+ - Required: No
+
 Specifies the button's style.
 
 The accepted values are:
@@ -188,6 +192,3 @@ The accepted values are:
 2. `'secondary'` (the default button styles)
 3. `'tertiary'` (the text-based button styles)
 4. `'link'` (the link button styles)
-
- - Type: `"link" | "primary" | "secondary" | "tertiary"`
- - Required: No

package/src/button/style.scss

@@ -9,7 +9,6 @@
 	display: inline-flex;
 	text-decoration: none;
 	font-family: inherit;
-	font-weight: normal;
 	font-size: $default-font-size;
 	margin: 0;
 	border: 0;
@@ -139,8 +138,10 @@
 		color: $components-color-accent;
 		background: transparent;
 
-		&:hover:not(:disabled, [aria-disabled="true"]) {
-			box-shadow: inset 0 0 0 $border-width $components-color-accent-darker-10;
+		&:hover:not(:disabled, [aria-disabled="true"], .is-pressed) {
+			box-shadow: inset 0 0 0 $border-width $components-color-accent-darker-20;
+			color: $components-color-accent-darker-20;
+			background: color-mix(in srgb, $components-color-accent 4%, transparent);
 		}
 
 		&:disabled:not(:focus),
@@ -164,15 +165,12 @@
 		background: transparent;
 
 		&:hover:not(:disabled, [aria-disabled="true"]) {
-			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
-			/* stylelint-disable-next-line declaration-property-value-disallowed-list -- Allow tertiary buttons to use colors from the user admin color scheme. */
-			background: rgba(var(--wp-admin-theme-color--rgb), 0.04);
+			background: color-mix(in srgb, $components-color-accent 4%, transparent);
+			color: $components-color-accent-darker-20;
 		}
 
 		&:active:not(:disabled, [aria-disabled="true"]) {
-			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
-			/* stylelint-disable-next-line declaration-property-value-disallowed-list -- Allow tertiary buttons to use colors from the user admin color scheme. */
-			background: rgba(var(--wp-admin-theme-color--rgb), 0.08);
+			background: color-mix(in srgb, $components-color-accent 8%, transparent);
 		}
 
 		// Pull left if the tertiary button stands alone after a description, so as to vertically align with items above.
@@ -220,7 +218,8 @@
 			}
 		}
 
-		&.is-tertiary {
+		&.is-tertiary,
+		&.is-secondary {
 			&:hover:not(:disabled, [aria-disabled="true"]) {
 				background: rgba($alert-red, 0.04);
 			}

package/src/button/test/index.tsx

@@ -6,19 +6,26 @@ import { render, screen } from '@testing-library/react';
 /**
  * WordPress dependencies
  */
-import { createRef } from '@wordpress/element';
+import { createRef, forwardRef } from '@wordpress/element';
 import { plusCircle } from '@wordpress/icons';
 
 /**
  * Internal dependencies
  */
-import Button from '..';
+import _Button from '..';
 import Tooltip from '../../tooltip';
 import cleanupTooltip from '../../tooltip/test/utils';
 import { press } from '@ariakit/test';
 
 jest.mock( '../../icon', () => () => <div data-testid="test-icon" /> );
 
+const Button = forwardRef(
+	(
+		props: React.ComponentProps< typeof _Button >,
+		ref: React.ForwardedRef< unknown >
+	) => <_Button __next40pxDefaultSize { ...props } ref={ ref } />
+);
+
 describe( 'Button', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render a button element with only one class', () => {

package/src/button-group/README.md

@@ -1,5 +1,9 @@
 # ButtonGroup
 
+<div class="callout callout-alert">
+	This component is deprecated. Use `ToggleGroupControl` instead.
+</div>
+
 ButtonGroup can be used to group any related buttons together. To emphasize related buttons, a group should share a common container.
 
 ![ButtonGroup component](https://wordpress.org/gutenberg/files/2018/12/s_96EC471FE9C9D91A996770229947AAB54A03351BDE98F444FD3C1BF0CED365EA_1541792995815_ButtonGroup.png)