@wordpress/components 28.14.1-next.cd6172eb0.0 → 29.0.0

package/src/button/README.md

@@ -1,304 +1,193 @@
 # Button
 
-Buttons let users take actions and make choices with a single click or tap.
+<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->
 
-![Button components](https://make.wordpress.org/design/files/2019/03/button.png)
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-button--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
 
-## Design guidelines
-
-### Usage
-
-Buttons tell users what actions they can take and give them a way to interact with the interface. You’ll find them throughout a UI, particularly in places like:
-
--   Modals
--   Forms
--   Toolbars
-
-### Best practices
-
-Buttons should:
-
--   **Be clearly and accurately labeled.**
--   **Clearly communicate that clicking or tapping will trigger an action.**
--   **Use established colors appropriately.** For example, only use red buttons for actions that are difficult or impossible to undo.
--   **Prioritize the most important actions.** This helps users focus. Too many calls to action on one screen can be confusing, making users unsure what to do next.
--   **Have consistent locations in the interface.**
-
-### Content guidelines
-
-Buttons should be clear and predictable—users should be able to anticipate what will happen when they click a button. Never deceive a user by mislabeling a button.
-
-Buttons text should lead with a strong verb that encourages action, and add a noun that clarifies what will actually change. The only exceptions are common actions like Save, Close, Cancel, or OK. Otherwise, use the {verb}+{noun} format to ensure that your button gives the user enough information.
-
-Button text should also be quickly scannable — avoid unnecessary words and articles like the, an, or a.
-
-### Types
-
-#### Link button
-
-Link buttons have low emphasis. They don’t stand out much on the page, so they’re used for less-important actions. What’s less important can vary based on context, but it’s usually a supplementary action to the main action we want someone to take. Link buttons are also useful when you don’t want to distract from the content.
-
-![Link button](https://make.wordpress.org/design/files/2019/03/link-button.png)
-
-#### Default button
-
-Default buttons have medium emphasis. The button appearance helps differentiate them from the page background, so they’re useful when you want more emphasis than a link button offers.
-
-![Default button](https://make.wordpress.org/design/files/2019/03/default-button.png)
-
-#### Primary button
-
-Primary buttons have high emphasis. Their color fill and shadow means they pop off the background.
-
-Since a high-emphasis button commands the most attention, a layout should contain a single primary button. This makes it clear that other buttons have less importance and helps users understand when an action requires their attention.
-
-![Primary button](https://make.wordpress.org/design/files/2019/03/primary-button.png)
-
-#### Text label
-
-All button types use text labels to describe the action that happens when a user taps a button. If there’s no text label, there needs to be a [label](#label) added and an icon to signify what the button does.
-
-![](https://make.wordpress.org/design/files/2019/03/do-link-button.png)
-
-**Do**
-Use color to distinguish link button labels from other text.
-
-![](https://make.wordpress.org/design/files/2019/03/dont-wrap-button-text.png)
-
-**Don’t**
-Don’t wrap button text. For maximum legibility, keep text labels on a single line.
-
-### Hierarchy
-
-![A layout with a single prominent button](https://make.wordpress.org/design/files/2019/03/button.png)
-
-A layout should contain a single prominently-located button. If multiple buttons are required, a single high-emphasis button can be joined by medium- and low-emphasis buttons mapped to less-important actions. When using multiple buttons, make sure the available state of one button doesn’t look like the disabled state of another.
-
-![A diagram showing high emphasis at the top, medium emphasis in the middle, and low emphasis at the bottom](https://make.wordpress.org/design/files/2019/03/button-hierarchy.png)
-
-A button’s level of emphasis helps determine its appearance, typography, and placement.
-
-#### Placement
-
-Use button types to express different emphasis levels for all the actions a user can perform.
-
-![A link, default, and primary button](https://make.wordpress.org/design/files/2019/03/button-layout.png)
-
-This screen layout uses:
-
-1. A primary button for high emphasis.
-2. A default button for medium emphasis.
-3. A link button for low emphasis.
-
-Placement best practices:
-
--   **Do**: When using multiple buttons in a row, show users which action is more important by placing it next to a button with a lower emphasis (e.g. a primary button next to a default button, or a default button next to a link button).
--   **Don’t**: Don’t place two primary buttons next to one another — they compete for focus. Only use one primary button per view.
--   **Don’t**: Don’t place a button below another button if there is space to place them side by side.
--   **Caution**: Avoid using too many buttons on a single page. When designing pages in the app or website, think about the most important actions for users to take. Too many calls to action can cause confusion and make users unsure what to do next — we always want users to feel confident and capable.
-
-## Development guidelines
-
-### Usage
-
-Renders a button with default style.
+Lets users take actions and make choices with a single click or tap.
 
 ```jsx
 import { Button } from '@wordpress/components';
-
-const MyButton = () => <Button variant="secondary">Click me!</Button>;
+const Mybutton = () => (
+  <Button
+    variant="primary"
+    onClick={ handleClick }
+  >
+    Click here
+  </Button>
+);
 ```
+## Props
 
-### Props
+### `__next40pxDefaultSize`
 
-The presence of a `href` prop determines whether an `anchor` element is rendered instead of a `button`.
+Start opting into the larger default height that will become the
+default size in a future version.
 
-Props not included in this set will be applied to the `a` or `button` element.
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-#### `accessibleWhenDisabled`: `boolean`
+### `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 can cause accessibility issues, by hiding their presence from screen reader users, or by preventing focus from returning to a trigger element.
+In most cases, it is recommended to set this to `true`. Disabling a control without maintaining focusability
+can cause accessibility issues, by hiding their presence from screen reader users,
+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.
+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.
 
--   Required: No
--   Default: `false`
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-#### `children`: `ReactNode`
+### `children`
 
 The button's children.
 
--   Required: No
+ - Type: `ReactNode`
+ - Required: No
 
-#### `className`: `string`
+### `description`
 
-An optional additional class name to apply to the rendered button.
+A visually hidden accessible description for the button.
 
--   Required: No
+ - Type: `string`
+ - Required: No
 
-#### `description`: `string`
+### `disabled`
 
-An accessible description for the button.
-
--   Required: No
-
-#### `disabled`: `boolean`
-
-Whether the button is disabled. If `true`, this will force a `button` element to be rendered, even when an `href` is given.
+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`.
 
--   Required: No
+ - Type: `boolean`
+ - Required: No
 
-#### `href`: `string`
+### `href`
 
 If provided, renders `a` instead of `button`.
 
--   Required: No
+ - Type: `string`
+ - Required: Yes
 
-#### `icon`: `IconProps< unknown >[ 'icon' ]`
+### `icon`
 
-If provided, renders an [Icon](/packages/components/src/icon/README.md) component inside the button.
+If provided, renders an Icon component inside the button.
 
--   Required: No
+ - Type: `IconType`
+ - Required: No
 
-#### `iconPosition`: `'left' | 'right'`
+### `iconPosition`
 
-If provided with `icon`, sets the position of icon relative to the `text`. Available options are `left|right`.
+If provided with `icon`, sets the position of icon relative to the `text`.
 
--   Required: No
--   Default: `left`
+ - Type: `"left" | "right"`
+ - Required: No
+ - Default: `'left'`
 
-#### `iconSize`: `IconProps< unknown >[ 'size' ]`
+### `iconSize`
 
-If provided with `icon`, sets the icon size. Please refer to the [Icon](/packages/components/src/icon/README.md) component for more details regarding the default value of its `size` prop.
+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.
 
--   Required: No
+ - Type: `number`
+ - Required: No
 
-#### `isBusy`: `boolean`
+### `isBusy`
 
 Indicates activity while a action is being performed.
 
--   Required: No
+ - Type: `boolean`
+ - Required: No
 
-#### `isDestructive`: `boolean`
+### `isDestructive`
 
 Renders a red text-based button style to indicate destructive behavior.
 
--   Required: No
-
-#### `isLink`: `boolean`
+ - Type: `boolean`
+ - Required: No
 
-Deprecated: Renders a button with an anchor style.
-Use `variant` prop with `link` value instead.
-
--   Required: No
--   Default: `false`
-
-#### `isPressed`: `boolean`
+### `isPressed`
 
 Renders a pressed button style.
 
-If the native `aria-pressed` attribute is also set, it will take precedence.
-
--   Required: No
-
-#### `isPrimary`: `boolean`
+ - Type: `boolean`
+ - Required: No
 
-Deprecated: Renders a primary button style.
-Use `variant` prop with `primary` value instead.
+### `label`
 
--   Required: No
--   Default: `false`
+Sets the `aria-label` of the component, if none is provided.
+Sets the Tooltip content if `showTooltip` is provided.
 
-#### `isSecondary`: `boolean`
+ - Type: `string`
+ - Required: No
 
-Deprecated: Renders a default button style.
-Use `variant` prop with `secondary` value instead.
+### `shortcut`
 
--   Required: No
--   Default: `false`
+If provided with `showTooltip`, appends the Shortcut label to the tooltip content.
+If an object is provided, it should contain `display` and `ariaLabel` keys.
 
-#### `isSmall`: `boolean`
+ - Type: `string | { display: string; ariaLabel: string; }`
+ - Required: No
 
-Decreases the size of the button.
+### `showTooltip`
 
-Deprecated in favor of the `size` prop. If both props are defined, the `size` prop will take precedence.
+If provided, renders a Tooltip component for the button.
 
--   Required: No
+ - Type: `boolean`
+ - Required: No
 
-#### `isTertiary`: `boolean`
-
-Deprecated: Renders a text-based button style.
-Use `variant` prop with `tertiary` value instead.
-
--   Required: No
--   Default: `false`
-
-#### `label`: `string`
-
-Sets the `aria-label` of the component, if none is provided. Sets the Tooltip content if `showTooltip` is provided.
-
--   Required: No
-
-#### `shortcut`: `string | { display: string; ariaLabel: string; }`
-
-If provided with `showTooltip`, appends the Shortcut label to the tooltip content. If an object is provided, it should contain `display` and `ariaLabel` keys.
-
--   Required: No
-
-#### `showTooltip`: `boolean`
-
-If provided, renders a [Tooltip](/packages/components/src/tooltip/README.md) component for the button.
-
--   Required: No
-
-#### `size`: `'default'` | `'compact'` | `'small'`
+### `size`
 
 The size of the button.
 
--   `'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.
+- `'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.
 
 If the deprecated `isSmall` prop is also defined, this prop will take precedence.
 
--   Required: No
--   Default: `'default'`
-
-#### `target`: `string`
+ - Type: `"small" | "default" | "compact"`
+ - Required: No
+ - Default: `'default'`
 
-If provided with `href`, sets the `target` attribute to the `a`.
-
--   Required: No
-
-#### `text`: `string`
+### `text`
 
 If provided, displays the given text inside the button. If the button contains children elements, the text is displayed before them.
 
--   Required: No
+ - Type: `string`
+ - Required: No
 
-#### `tooltipPosition`: `PopoverProps[ 'position' ]`
+### `tooltipPosition`
 
-If provided with`showTooltip`, sets the position of the tooltip. Please refer to the [Tooltip](/packages/components/src/tooltip/README.md) component for more details regarding the defaults.
+If provided with `showTooltip`, sets the position of the tooltip.
+Please refer to the Tooltip component for more details regarding the defaults.
 
--   Required: No
+ - Type: `"top" | "middle" | "bottom" | "top center" | "top left" | "top right" | "middle center" | "middle left" | "middle right" | "bottom center" | ...`
+ - Required: No
 
-#### `variant`: `'primary' | 'secondary' | 'tertiary' | 'link'`
+### `target`
 
-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), and `'link'` (the link button styles).
+If provided with `href`, sets the `target` attribute to the `a`.
 
--   Required: No
+ - Type: `string`
+ - Required: No
 
-#### `__next40pxDefaultSize`: `boolean`
+### `variant`
 
-Start opting into the larger default height that will become the default size in a future version.
+Specifies the button's style.
 
-- Required: No
-- Default: `false`
+The accepted values are:
 
-## Related components
+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)
 
--   To group buttons together, use the [ButtonGroup](/packages/components/src/button-group/README.md) component.
+ - Type: `"link" | "primary" | "secondary" | "tertiary"`
+ - Required: No

package/src/button/docs-manifest.json

@@ -0,0 +1,5 @@
+{
+	"$schema": "../../schemas/docs-manifest.json",
+	"displayName": "Button",
+	"filePath": "./index.tsx"
+}

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/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/stories/index.story.tsx

@@ -13,7 +13,7 @@ const meta: Meta< typeof ButtonGroup > = {
 	title: 'Components/ButtonGroup',
 	component: ButtonGroup,
 	argTypes: {
-		children: { control: { type: null } },
+		children: { control: false },
 	},
 	parameters: {
 		controls: { expanded: true },

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

@@ -26,10 +26,10 @@ const meta: Meta< typeof Card > = {
 	id: 'components-card',
 	argTypes: {
 		as: {
-			control: { type: null },
+			control: false,
 		},
 		children: {
-			control: { type: null },
+			control: false,
 		},
 	},
 	parameters: {

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

@@ -24,7 +24,7 @@ const meta: Meta< typeof CheckboxControl > = {
 			action: 'onChange',
 		},
 		checked: {
-			control: { type: null },
+			control: false,
 		},
 		help: { control: { type: 'text' } },
 	},

package/src/circular-option-picker/stories/index.story.tsx

@@ -32,8 +32,8 @@ const meta: Meta< typeof CircularOptionPicker > = {
 			CircularOptionPicker.DropdownLinkAction,
 	},
 	argTypes: {
-		actions: { control: { type: null } },
-		options: { control: { type: null } },
+		actions: { control: false },
+		options: { control: false },
 		children: { control: { type: 'text' } },
 	},
 	parameters: {

package/src/color-palette/stories/index.story.tsx

@@ -18,9 +18,9 @@ const meta: Meta< typeof ColorPalette > = {
 	id: 'components-colorpalette',
 	component: ColorPalette,
 	argTypes: {
-		as: { control: { type: null } },
-		onChange: { action: 'onChange', control: { type: null } },
-		value: { control: { type: null } },
+		as: { control: false },
+		onChange: { action: 'onChange', control: false },
+		value: { control: false },
 	},
 	parameters: {
 		controls: { expanded: true },

package/src/color-picker/stories/index.story.tsx

@@ -13,8 +13,8 @@ const meta: Meta< typeof ColorPicker > = {
 	title: 'Components/Selection & Input/Color/ColorPicker',
 	id: 'components-colorpicker',
 	argTypes: {
-		as: { control: { type: null } },
-		color: { control: { type: null } },
+		as: { control: false },
+		color: { control: false },
 	},
 	parameters: {
 		actions: { argTypesRegex: '^on.*' },

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

@@ -38,7 +38,7 @@ const meta: Meta< typeof ComboboxControl > = {
 	id: 'components-comboboxcontrol',
 	component: ComboboxControl,
 	argTypes: {
-		value: { control: { type: null } },
+		value: { control: false },
 	},
 	parameters: {
 		actions: { argTypesRegex: '^on.*' },

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

@@ -36,9 +36,9 @@ const meta: Meta< typeof Composite > = {
 		'Composite.Context': Composite.Context,
 	},
 	argTypes: {
-		children: { control: { type: null } },
-		render: { control: { type: null } },
-		setActiveId: { control: { type: null } },
+		children: { control: false },
+		render: { control: false },
+		setActiveId: { control: false },
 		focusLoop: {
 			control: 'select',
 			options: [ true, false, 'horizontal', 'vertical', 'both' ],

package/src/confirm-dialog/stories/index.story.tsx

@@ -20,7 +20,7 @@ const meta: Meta< typeof ConfirmDialog > = {
 	id: 'components-experimental-confirmdialog',
 	argTypes: {
 		isOpen: {
-			control: { type: null },
+			control: false,
 		},
 	},
 	parameters: {

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

@@ -154,11 +154,11 @@ function CustomSelectControl< T extends CustomSelectOption >(
 	const renderSelectedValueHint = () => {
 		const selectedOptionHint = options
 			?.map( applyOptionDeprecations )
-			?.find( ( { name } ) => currentValue === name )?.hint;
+			?.find( ( { name } ) => store.getState().value === name )?.hint;
 
 		return (
 			<Styled.SelectedExperimentalHintWrapper>
-				{ currentValue }
+				{ store.getState().value }
 				{ selectedOptionHint && (
 					<Styled.SelectedExperimentalHintItem
 						// Keeping the classname for legacy reasons

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

@@ -18,8 +18,8 @@ const meta: Meta< typeof CustomSelectControl > = {
 	component: CustomSelectControl,
 	id: 'components-customselectcontrol',
 	argTypes: {
-		onChange: { control: { type: null } },
-		value: { control: { type: null } },
+		onChange: { control: false },
+		value: { control: false },
 	},
 	parameters: {
 		actions: { argTypesRegex: '^on.*' },