@wordpress/components 29.0.1-next.a9f418477.0 → 29.1.0

package/src/button/stories/best-practices.mdx

@@ -0,0 +1,31 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Components/Actions/Button/Best Practices" />
+
+# Button
+
+## Usage
+Buttons indicate available actions and allow user interaction within the interface. As key elements in the WordPress UI, they appear in toolbars, modals, and forms. Default buttons support most actions, while primary buttons emphasize the main action in a view. Secondary buttons pair as secondary actions next to a primary action. 
+
+Each layout contains one prominently placed, high-emphasis button. If you need multiple buttons, use one primary button for the main action, secondary for the rest of the actions and tertiary sparingly when an action needs to not stand out at all.
+
+### Sizes
+
+- `'default'`: For normal text-label buttons, unless it is a toggle button.
+- `'compact'`: For toggle buttons, icon buttons, and buttons when used in context of either.
+- `'small'`: For icon buttons associated with more advanced or auxiliary features.
+
+## Best practices
+
+- Label buttons to show that a click or tap initiates an action.
+- Use established color conventions; for example, reserve red buttons for irreversible or dangerous actions.
+- Avoid crowding the screen with multiple calls to action, which confuses users.
+- Keep button locations consistent across the interface.
+
+## Content guidelines
+
+Buttons should be clear and predictable, showing users what will happen when clicked. Make labels reflect actions accurately to avoid confusion. 
+
+Start button text with a strong action verb and include a noun to specify the change, except for common actions like Save, Close, Cancel, or OK. 
+
+For other actions, use a `{verb}+{noun}` format for context. Keep button text brief and remove unnecessary words like "the," "an," or "a" for easy scanning.

package/src/button/stories/index.story.tsx

@@ -65,30 +65,48 @@ Default.args = {
 	children: 'Code is poetry',
 };
 
+/**
+ * Primary buttons stand out with bold color fills, making them distinct
+ * from the background. Since they naturally draw attention, each layout should contain
+ * only one primary button to guide users toward the most important action.
+ */
 export const Primary = Template.bind( {} );
 Primary.args = {
 	...Default.args,
 	variant: 'primary',
 };
 
+/**
+ * Secondary buttons complement primary buttons. Use them for standard actions that may appear alongside a primary action.
+ */
 export const Secondary = Template.bind( {} );
 Secondary.args = {
 	...Default.args,
 	variant: 'secondary',
 };
 
+/**
+ * Tertiary buttons have minimal emphasis. Use them sparingly to subtly highlight an action.
+ */
 export const Tertiary = Template.bind( {} );
 Tertiary.args = {
 	...Default.args,
 	variant: 'tertiary',
 };
 
+/**
+ * Link buttons have low emphasis and blend into the page, making them suitable for supplementary actions,
+ * especially those involving navigation away from the current view.
+ */
 export const Link = Template.bind( {} );
 Link.args = {
 	...Default.args,
 	variant: 'link',
 };
 
+/**
+ * Use this variant for irreversible actions. Apply sparingly and only for actions with significant impact.
+ */
 export const IsDestructive = Template.bind( {} );
 IsDestructive.args = {
 	...Default.args,

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

@@ -111,11 +111,13 @@ type BaseButtonProps = {
 	tooltipPosition?: PopoverProps[ 'position' ];
 	/**
 	 * Specifies the button's style.
+	 *
 	 * The accepted values are:
-	 * 'primary' (the primary button styles)
-	 * 'secondary' (the default button styles)
-	 * 'tertiary' (the text-based button styles)
-	 * 'link' (the link button styles)
+	 *
+	 * 1. `'primary'` (the primary button styles)
+	 * 2. `'secondary'` (the default button styles)
+	 * 3. `'tertiary'` (the text-based button styles)
+	 * 4. `'link'` (the link button styles)
 	 */
 	variant?: 'primary' | 'secondary' | 'tertiary' | 'link';
 };

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)

package/src/button-group/index.tsx

@@ -8,6 +8,7 @@ import type { ForwardedRef } from 'react';
  * WordPress dependencies
  */
 import { forwardRef } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -19,9 +20,16 @@ function UnforwardedButtonGroup(
 	props: WordPressComponentProps< ButtonGroupProps, 'div', false >,
 	ref: ForwardedRef< HTMLDivElement >
 ) {
-	const { className, ...restProps } = props;
+	const { className, __shouldNotWarnDeprecated, ...restProps } = props;
 	const classes = clsx( 'components-button-group', className );
 
+	if ( ! __shouldNotWarnDeprecated ) {
+		deprecated( 'wp.components.ButtonGroup', {
+			since: '6.8',
+			alternative: 'wp.components.__experimentalToggleGroupControl',
+		} );
+	}
+
 	return (
 		<div ref={ ref } role="group" className={ classes } { ...restProps } />
 	);
@@ -31,6 +39,8 @@ function UnforwardedButtonGroup(
  * ButtonGroup can be used to group any related buttons together. To emphasize
  * related buttons, a group should share a common container.
  *
+ * @deprecated Use `ToggleGroupControl` instead.
+ *
  * ```jsx
  * import { Button, ButtonGroup } from '@wordpress/components';
  *

package/src/button-group/stories/index.story.tsx

@@ -9,8 +9,15 @@ import type { Meta, StoryObj } from '@storybook/react';
 import ButtonGroup from '..';
 import Button from '../../button';
 
+/**
+ * ButtonGroup can be used to group any related buttons together.
+ * To emphasize related buttons, a group should share a common container.
+ *
+ * This component is deprecated. Use `ToggleGroupControl` instead.
+ */
 const meta: Meta< typeof ButtonGroup > = {
-	title: 'Components/ButtonGroup',
+	title: 'Components (Deprecated)/ButtonGroup',
+	id: 'components-buttongroup',
 	component: ButtonGroup,
 	argTypes: {
 		children: { control: false },

package/src/button-group/types.ts

@@ -8,4 +8,11 @@ export type ButtonGroupProps = {
 	 * The children elements.
 	 */
 	children: ReactNode;
+	/**
+	 * Do not throw a warning for component deprecation.
+	 * For internal components of other components that already throw the warning.
+	 *
+	 * @ignore
+	 */
+	__shouldNotWarnDeprecated?: boolean;
 };

package/src/custom-select-control/index.tsx

@@ -149,7 +149,7 @@ function CustomSelectControl< T extends CustomSelectOption >(
 			);
 		} );
 
-	const { value: currentValue } = store.getState();
+	const currentValue = Ariakit.useStoreState( store, 'value' );
 
 	const renderSelectedValueHint = () => {
 		const selectedOptionHint = options

package/src/custom-select-control-v2/custom-select.tsx

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import * as Ariakit from '@ariakit/react';
-import { useStoreState } from '@ariakit/react';
 
 /**
  * WordPress dependencies
@@ -63,7 +62,7 @@ const CustomSelectButton = ( {
 		CustomSelectStore,
 	'onChange'
 > ) => {
-	const { value: currentValue } = useStoreState( store );
+	const { value: currentValue } = Ariakit.useStoreState( store );
 
 	const computedRenderSelectedValue = useMemo(
 		() => renderSelectedValue ?? defaultRenderSelectedValue,

package/src/custom-select-control-v2/stories/index.story.tsx

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import type { Meta, StoryFn } from '@storybook/react';
+import { fn } from '@storybook/test';
 
 /**
  * WordPress dependencies
@@ -44,6 +45,9 @@ const meta: Meta< typeof CustomSelectControlV2 > = {
 			</div>
 		),
 	],
+	args: {
+		onChange: fn(),
+	},
 };
 export default meta;
 

package/src/date-time/date/index.tsx

@@ -306,6 +306,7 @@ function Day( {
 
 	return (
 		<DayButton
+			__next40pxDefaultSize
 			ref={ ref }
 			className="components-datetime__date__day" // Unused, for backwards compatibility.
 			disabled={ isInvalid }

package/src/dimension-control/index.tsx

@@ -113,6 +113,7 @@ export function DimensionControl( props: DimensionControlProps ) {
 		<ContextSystemProvider value={ CONTEXT_VALUE }>
 			<SelectControl
 				__next40pxDefaultSize={ __next40pxDefaultSize }
+				__shouldNotWarnDeprecated36pxSize
 				__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 				className={ clsx(
 					className,

package/src/dimension-control/test/__snapshots__/index.test.js.snap

@@ -63,7 +63,7 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
 }
 
 .emotion-12 {
-  color: #1e1e1e;
+  color: var(--wp-components-color-foreground, #1e1e1e);
   line-height: 1.4;
   margin: 0;
   text-wrap: balance;
@@ -345,7 +345,7 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
 }
 
 .emotion-12 {
-  color: #1e1e1e;
+  color: var(--wp-components-color-foreground, #1e1e1e);
   line-height: 1.4;
   margin: 0;
   text-wrap: balance;
@@ -637,7 +637,7 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
 }
 
 .emotion-12 {
-  color: #1e1e1e;
+  color: var(--wp-components-color-foreground, #1e1e1e);
   line-height: 1.4;
   margin: 0;
   text-wrap: balance;
@@ -941,7 +941,7 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
 }
 
 .emotion-12 {
-  color: #1e1e1e;
+  color: var(--wp-components-color-foreground, #1e1e1e);
   line-height: 1.4;
   margin: 0;
   text-wrap: balance;

package/src/disabled/stories/index.story.tsx

@@ -55,6 +55,7 @@ const Form = () => {
 			/>
 			<SelectControl
 				__nextHasNoMarginBottom
+				__next40pxDefaultSize
 				label="Select Control"
 				onChange={ () => {} }
 				options={ [

package/src/drop-zone/stories/index.story.tsx

@@ -21,7 +21,13 @@ export default meta;
 
 const Template: StoryFn< typeof DropZone > = ( props ) => {
 	return (
-		<div style={ { background: 'lightgray', padding: 16 } }>
+		<div
+			style={ {
+				background: 'lightgray',
+				padding: 32,
+				position: 'relative',
+			} }
+		>
 			Drop something here
 			<DropZone { ...props } />
 		</div>

package/src/font-size-picker/styles.ts

@@ -16,6 +16,7 @@ export const Container = styled.fieldset`
 	border: 0;
 	margin: 0;
 	padding: 0;
+	display: contents;
 `;
 
 export const Header = styled( HStack )`

package/src/form-file-upload/README.md

@@ -19,60 +19,64 @@ const MyFormFileUpload = () => (
   </FormFileUpload>
 );
 ```
+
 ## Props
 
 ### `__next40pxDefaultSize`
 
-Start opting into the larger default height that will become the default size in a future version.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
+Start opting into the larger default height that will become the default size in a future version.
+
 ### `accept`
 
+ - Type: `string`
+ - Required: No
+
 A string passed to the `input` element that tells the browser which
 [file types](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#Unique_file_type_specifiers)
 can be uploaded by the user. e.g: `image/*,video/*`.
 
- - Type: `string`
- - Required: No
-
 ### `children`
 
-Children are passed as children of `Button`.
-
  - Type: `ReactNode`
  - Required: No
 
+Children are passed as children of `Button`.
+
 ### `icon`
 
+ - Type: `IconType`
+ - Required: No
+
 The icon to render in the default button.
 
 See the `Icon` component docs for more information.
 
- - Type: `IconType`
- - Required: No
-
 ### `multiple`
 
-Whether to allow multiple selection of files or not.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
+Whether to allow multiple selection of files or not.
+
 ### `onChange`
 
+ - Type: `ChangeEventHandler<HTMLInputElement>`
+ - Required: Yes
+
 Callback function passed directly to the `input` file element.
 
 Select files will be available in `event.currentTarget.files`.
 
- - Type: `ChangeEventHandler<HTMLInputElement>`
- - Required: Yes
-
 ### `onClick`
 
+ - Type: `MouseEventHandler<HTMLInputElement>`
+ - Required: No
+
 Callback function passed directly to the `input` file element.
 
 This can be useful when you want to force a `change` event to fire when
@@ -89,17 +93,14 @@ an empty string in the `onClick` function.
 </FormFileUpload>
 ```
 
- - Type: `MouseEventHandler<HTMLInputElement>`
- - Required: No
-
 ### `render`
 
+ - Type: `(arg: { openFileDialog: () => void; }) => ReactNode`
+ - Required: No
+
 Optional callback function used to render the UI.
 
 If passed, the component does not render the default UI (a button) and
 calls this function to render it. The function receives an object with
 property `openFileDialog`, a function that, when called, opens the browser
 native file upload modal window.
-
- - Type: `(arg: { openFileDialog: () => void; }) => ReactNode`
- - Required: No

package/src/gradient-picker/README.md

@@ -43,114 +43,115 @@ const MyGradientPicker = () => {
   );
 };
 ```
+
 ## Props
 
 ### `__experimentalIsRenderedInSidebar`
 
-Whether this is rendered in the sidebar.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `asButtons`
+Whether this is rendered in the sidebar.
 
-Whether the control should present as a set of buttons,
-each with its own tab stop.
+### `asButtons`
 
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `aria-label`
+Whether the control should present as a set of buttons,
+each with its own tab stop.
 
-A label to identify the purpose of the control.
+### `aria-label`
 
  - Type: `string`
  - Required: No
 
-### `aria-labelledby`
+A label to identify the purpose of the control.
 
-An ID of an element to provide a label for the control.
+### `aria-labelledby`
 
  - Type: `string`
  - Required: No
 
-### `className`
+An ID of an element to provide a label for the control.
 
-The class name added to the wrapper.
+### `className`
 
  - Type: `string`
  - Required: No
 
-### `clearable`
+The class name added to the wrapper.
 
-Whether the palette should have a clearing button or not.
+### `clearable`
 
  - Type: `boolean`
  - Required: No
  - Default: `true`
 
-### `disableCustomGradients`
+Whether the palette should have a clearing button or not.
 
-If true, the gradient picker will not be displayed and only defined
-gradients from `gradients` will be shown.
+### `disableCustomGradients`
 
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `enableAlpha`
+If true, the gradient picker will not be displayed and only defined
+gradients from `gradients` will be shown.
 
-Whether to enable alpha transparency options in the picker.
+### `enableAlpha`
 
  - Type: `boolean`
  - Required: No
  - Default: `true`
 
+Whether to enable alpha transparency options in the picker.
+
 ### `gradients`
 
+ - Type: `GradientsProp`
+ - Required: No
+ - Default: `[]`
+
 An array of objects as predefined gradients displayed above the gradient
 selector. Alternatively, if there are multiple sets (or 'origins') of
 gradients, you can pass an array of objects each with a `name` and a
 `gradients` array which will in turn contain the predefined gradient objects.
 
- - Type: `GradientsProp`
- - Required: No
- - Default: `[]`
-
 ### `headingLevel`
 
-The heading level. Only applies in cases where gradients are provided
-from multiple origins (i.e. when the array passed as the `gradients` prop
-contains two or more items).
-
  - Type: `1 | 2 | 3 | 4 | 5 | 6 | "1" | "2" | "3" | "4" | ...`
  - Required: No
  - Default: `2`
 
-### `loop`
+The heading level. Only applies in cases where gradients are provided
+from multiple origins (i.e. when the array passed as the `gradients` prop
+contains two or more items).
 
-Prevents keyboard interaction from wrapping around.
-Only used when `asButtons` is not true.
+### `loop`
 
  - Type: `boolean`
  - Required: No
  - Default: `true`
 
-### `onChange`
+Prevents keyboard interaction from wrapping around.
+Only used when `asButtons` is not true.
 
-The function called when a new gradient has been defined. It is passed to
-the `currentGradient` as an argument.
+### `onChange`
 
  - Type: `(currentGradient: string) => void`
  - Required: Yes
 
-### `value`
+The function called when a new gradient has been defined. It is passed to
+the `currentGradient` as an argument.
 
-The current value of the gradient. Pass a css gradient string (See default value for example).
-Optionally pass in a `null` value to specify no gradient is currently selected.
+### `value`
 
  - Type: `string`
  - Required: No
  - Default: `'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'`
+
+The current value of the gradient. Pass a css gradient string (See default value for example).
+Optionally pass in a `null` value to specify no gradient is currently selected.

package/src/heading/hook.ts

@@ -14,7 +14,7 @@ export function useHeading(
 	const {
 		as: asProp,
 		level = 2,
-		color = COLORS.gray[ 900 ],
+		color = COLORS.theme.foreground,
 		isBlock = true,
 		weight = CONFIG.fontWeightHeading as import('react').CSSProperties[ 'fontWeight' ],
 		...otherProps