@wordpress/components 28.12.0 → 28.13.0

package/src/gradient-picker/index.tsx

@@ -166,44 +166,44 @@ function Component( props: PickerProps< any > ) {
 }
 
 /**
- *  GradientPicker is a React component that renders a color gradient picker to
+ * GradientPicker is a React component that renders a color gradient picker to
  * define a multi step gradient. There's either a _linear_ or a _radial_ type
  * available.
  *
  * ```jsx
- *import { GradientPicker } from '@wordpress/components';
- *import { useState } from '@wordpress/element';
+ * import { useState } from 'react';
+ * import { GradientPicker } from '@wordpress/components';
  *
- *const myGradientPicker = () => {
- *	const [ gradient, setGradient ] = useState( null );
+ * const MyGradientPicker = () => {
+ *   const [ gradient, setGradient ] = useState( null );
  *
- *	return (
- *		<GradientPicker
- *			value={ gradient }
- *			onChange={ ( currentGradient ) => setGradient( currentGradient ) }
- *			gradients={ [
- *				{
- *					name: 'JShine',
- *					gradient:
- *						'linear-gradient(135deg,#12c2e9 0%,#c471ed 50%,#f64f59 100%)',
- *					slug: 'jshine',
- *				},
- *				{
- *					name: 'Moonlit Asteroid',
- *					gradient:
- *						'linear-gradient(135deg,#0F2027 0%, #203A43 0%, #2c5364 100%)',
- *					slug: 'moonlit-asteroid',
- *				},
- *				{
- *					name: 'Rastafarie',
- *					gradient:
- *						'linear-gradient(135deg,#1E9600 0%, #FFF200 0%, #FF0000 100%)',
- *					slug: 'rastafari',
- *				},
- *			] }
- *		/>
- *	);
- *};
+ *   return (
+ *     <GradientPicker
+ *       value={ gradient }
+ *       onChange={ ( currentGradient ) => setGradient( currentGradient ) }
+ *       gradients={ [
+ *         {
+ *           name: 'JShine',
+ *           gradient:
+ *             'linear-gradient(135deg,#12c2e9 0%,#c471ed 50%,#f64f59 100%)',
+ *           slug: 'jshine',
+ *         },
+ *         {
+ *           name: 'Moonlit Asteroid',
+ *           gradient:
+ *             'linear-gradient(135deg,#0F2027 0%, #203A43 0%, #2c5364 100%)',
+ *           slug: 'moonlit-asteroid',
+ *         },
+ *         {
+ *           name: 'Rastafarie',
+ *           gradient:
+ *             'linear-gradient(135deg,#1E9600 0%, #FFF200 0%, #FF0000 100%)',
+ *           slug: 'rastafari',
+ *         },
+ *       ] }
+ *     />
+ *   );
+ * };
  *```
  *
  */
@@ -247,6 +247,8 @@ export function GradientPicker( {
 						! disableCustomGradients && (
 							<CircularOptionPicker.ButtonAction
 								onClick={ clearGradient }
+								accessibleWhenDisabled
+								disabled={ ! value }
 							>
 								{ __( 'Clear' ) }
 							</CircularOptionPicker.ButtonAction>

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

@@ -13,7 +13,8 @@ import { useState } from '@wordpress/element';
 import GradientPicker from '..';
 
 const meta: Meta< typeof GradientPicker > = {
-	title: 'Components/GradientPicker',
+	title: 'Components/Selection & Input/Color/GradientPicker',
+	id: 'components-gradientpicker',
 	component: GradientPicker,
 	parameters: {
 		controls: { expanded: true },

package/src/gradient-picker/types.ts

@@ -36,7 +36,7 @@ type GradientPickerBaseProps = {
 	clearable?: boolean;
 	/**
 	 * The heading level. Only applies in cases where gradients are provided
-	 * from multiple origins (ie. when the array passed as the `gradients` prop
+	 * from multiple origins (i.e. when the array passed as the `gradients` prop
 	 * contains two or more items).
 	 *
 	 * @default 2
@@ -58,19 +58,17 @@ type GradientPickerBaseProps = {
 	loop?: boolean;
 } & (
 	| {
+			// TODO: [#54055] Either this or `aria-labelledby` should be required
 			/**
 			 * A label to identify the purpose of the control.
-			 *
-			 * @todo [#54055] Either this or `aria-labelledby` should be required
 			 */
 			'aria-label'?: string;
 			'aria-labelledby'?: never;
 	  }
 	| {
+			// TODO: [#54055] Either this or `aria-label` should be required
 			/**
 			 * An ID of an element to provide a label for the control.
-			 *
-			 * @todo [#54055] Either this or `aria-label` should be required
 			 */
 			'aria-labelledby'?: string;
 			'aria-label'?: never;

package/src/h-stack/stories/index.story.tsx

@@ -42,7 +42,8 @@ const JUSTIFICATIONS = {
 
 const meta: Meta< typeof HStack > = {
 	component: HStack,
-	title: 'Components (Experimental)/HStack',
+	title: 'Components (Experimental)/Layout/HStack',
+	id: 'components-experimental-hstack',
 	argTypes: {
 		as: {
 			control: { type: null },

package/src/higher-order/with-constrained-tabbing/README.md

@@ -22,8 +22,18 @@ const MyComponentWithConstrainedTabbing = () => {
 	const [ isConstrainedTabbing, setIsConstrainedTabbing ] = useState( false );
 	let form = (
 		<form>
-			<TextControl label="Input 1" onChange={ () => {} } />
-			<TextControl label="Input 2" onChange={ () => {} } />
+			<TextControl
+				__next40pxDefaultSize
+				__nextHasNoMarginBottom
+				label="Input 1"
+				onChange={ () => {} }
+			/>
+			<TextControl
+				__next40pxDefaultSize
+				__nextHasNoMarginBottom
+				label="Input 2"
+				onChange={ () => {} }
+			/>
 		</form>
 	);
 	if ( isConstrainedTabbing ) {
@@ -43,5 +53,5 @@ const MyComponentWithConstrainedTabbing = () => {
 			</Button>
 		</div>
 	);
-}
+};
 ```

package/src/higher-order/with-focus-return/README.md

@@ -13,7 +13,12 @@ import { withFocusReturn, TextControl, Button } from '@wordpress/components';
 const EnhancedComponent = withFocusReturn( () => (
 	<div>
 		Focus will return to the previous input when this component is unmounted
-		<TextControl autoFocus={ true } onChange={ () => {} } />
+		<TextControl
+			__nextHasNoMarginBottom
+			__next40pxDefaultSize
+			autoFocus={ true }
+			onChange={ () => {} }
+		/>
 	</div>
 ) );
 
@@ -27,6 +32,8 @@ const MyComponentWithFocusReturn = () => {
 	return (
 		<div>
 			<TextControl
+				__nextHasNoMarginBottom
+				__next40pxDefaultSize
 				placeholder="Type something"
 				value={ text }
 				onChange={ ( value ) => setText( value ) }
@@ -39,7 +46,7 @@ const MyComponentWithFocusReturn = () => {
 			) }
 		</div>
 	);
-}
+};
 ```
 
 `withFocusReturn` can optionally be called as a higher-order function creator. Provided an options object, a new higher-order function is returned.

package/src/icon/README.md

@@ -1,82 +1,39 @@
 # Icon
 
-Allows you to render a raw icon without any initial styling or wrappers.
+<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->
 
-## Usage
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-icon--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
 
-#### With a Dashicon
+Renders a raw icon without any initial styling or wrappers.
 
 ```jsx
-import { Icon } from '@wordpress/components';
+import { wordpress } from '@wordpress/icons';
 
-const MyIcon = () => <Icon icon="screenoptions" />;
+<Icon icon={ wordpress } />
 ```
-
-#### With a function
-
-```jsx
-import { Icon } from '@wordpress/components';
-
-const MyIcon = () => (
-	<Icon
-		icon={ () => (
-			<svg>
-				<path d="M5 4v3h5.5v12h3V7H19V4z" />
-			</svg>
-		) }
-	/>
-);
-```
-
-#### With a Component
-
-```jsx
-import { MyIconComponent } from '../my-icon-component';
-import { Icon } from '@wordpress/components';
-
-const MyIcon = () => <Icon icon={ MyIconComponent } />;
-```
-
-#### With an SVG
-
-```jsx
-import { Icon } from '@wordpress/components';
-
-const MyIcon = () => (
-	<Icon
-		icon={
-			<svg>
-				<path d="M5 4v3h5.5v12h3V7H19V4z" />
-			</svg>
-		}
-	/>
-);
-```
-
-#### Specifying a className
-
-```jsx
-import { Icon } from '@wordpress/components';
-
-const MyIcon = () => <Icon icon="screenoptions" className="example-class" />;
-```
-
 ## Props
 
-The component accepts the following props. Any additional props are passed through to the underlying icon element.
+### `icon`
 
-### icon
+The icon to render. In most cases, you should use an icon from
+[the `@wordpress/icons` package](https://wordpress.github.io/gutenberg/?path=/story/icons-icon--library).
 
-The icon to render. Supported values are: Dashicons (specified as strings), functions, Component instances and `null`.
+Other supported values are: component instances, functions,
+[Dashicons](https://developer.wordpress.org/resource/dashicons/)
+(specified as strings), and `null`.
 
--   Type: `String|Function|Component|null`
--   Required: No
--   Default: `null`
+The `size` value, as well as any other additional props, will be passed through.
 
-### size
+ - Type: `IconType`
+ - Required: No
+ - Default: `null`
+
+### `size`
 
 The size (width and height) of the icon.
 
--   Type: `Number`
--   Required: No
--   Default: `20` when a Dashicon is rendered, `24` for all other icons.
+Defaults to `20` when `icon` is a string (i.e. a Dashicon id), otherwise `24`.
+
+ - Type: `number`
+ - Required: No
+ - Default: `'string' === typeof icon ? 20 : 24`

package/src/icon/docs-manifest.json

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

package/src/icon/index.tsx

@@ -25,10 +25,22 @@ export type IconType =
 	| ( ( props: { size?: number } ) => JSX.Element )
 	| JSX.Element;
 
-interface BaseProps {
+type AdditionalProps< T > = T extends ComponentType< infer U >
+	? U
+	: T extends DashiconIconKey
+	? SVGProps< SVGSVGElement >
+	: {};
+
+export type Props = {
 	/**
-	 * The icon to render. Supported values are: Dashicons (specified as
-	 * strings), functions, Component instances and `null`.
+	 * The icon to render. In most cases, you should use an icon from
+	 * [the `@wordpress/icons` package](https://wordpress.github.io/gutenberg/?path=/story/icons-icon--library).
+	 *
+	 * Other supported values are: component instances, functions,
+	 * [Dashicons](https://developer.wordpress.org/resource/dashicons/)
+	 * (specified as strings), and `null`.
+	 *
+	 * The `size` value, as well as any other additional props, will be passed through.
 	 *
 	 * @default null
 	 */
@@ -36,19 +48,22 @@ interface BaseProps {
 	/**
 	 * The size (width and height) of the icon.
 	 *
-	 * @default `20` when a Dashicon is rendered, `24` for all other icons.
+	 * Defaults to `20` when `icon` is a string (i.e. a Dashicon id), otherwise `24`.
+	 *
+	 * @default `'string' === typeof icon ? 20 : 24`.
 	 */
 	size?: number;
-}
-
-type AdditionalProps< T > = T extends ComponentType< infer U >
-	? U
-	: T extends DashiconIconKey
-	? SVGProps< SVGSVGElement >
-	: {};
-
-export type Props = BaseProps & AdditionalProps< IconType >;
+} & AdditionalProps< IconType >;
 
+/**
+ * Renders a raw icon without any initial styling or wrappers.
+ *
+ * ```jsx
+ * import { wordpress } from '@wordpress/icons';
+ *
+ * <Icon icon={ wordpress } />
+ * ```
+ */
 function Icon( {
 	icon = null,
 	size = 'string' === typeof icon ? 20 : 24,

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

@@ -47,26 +47,68 @@ FillColor.args = {
 	...Default.args,
 };
 
+/**
+ * When `icon` is a function, it will be passed the `size` prop and any other additional props.
+ */
 export const WithAFunction = Template.bind( {} );
 WithAFunction.args = {
 	...Default.args,
-	icon: () => (
-		<SVG>
-			<Path d="M5 4v3h5.5v12h3V7H19V4z" />
-		</SVG>
+	icon: ( { size }: { size?: number } ) => (
+		<img
+			width={ size }
+			height={ size }
+			src="https://s.w.org/style/images/about/WordPress-logotype-wmark.png"
+			alt="WordPress"
+		/>
 	),
 };
+WithAFunction.parameters = {
+	docs: {
+		source: {
+			code: `
+<Icon
+  icon={ ( { size } ) => (
+    <img
+      width={ size }
+      height={ size }
+      src="https://s.w.org/style/images/about/WordPress-logotype-wmark.png"
+      alt="WordPress"
+    />
+  ) }
+/>
+		`,
+		},
+	},
+};
 
-const MyIconComponent = () => (
-	<SVG>
+const MyIconComponent = ( { size }: { size?: number } ) => (
+	<SVG width={ size } height={ size }>
 		<Path d="M5 4v3h5.5v12h3V7H19V4z" />
 	</SVG>
 );
 
+/**
+ * When `icon` is a component, it will be passed the `size` prop and any other additional props.
+ */
 export const WithAComponent = Template.bind( {} );
 WithAComponent.args = {
 	...Default.args,
-	icon: MyIconComponent,
+	icon: <MyIconComponent />,
+};
+WithAComponent.parameters = {
+	docs: {
+		source: {
+			code: `
+const MyIconComponent = ( { size } ) => (
+  <SVG width={ size } height={ size }>
+    <Path d="M5 4v3h5.5v12h3V7H19V4z" />
+  </SVG>
+);
+
+<Icon icon={ <MyIconComponent /> } />
+		`,
+		},
+	},
 };
 
 export const WithAnSVG = Template.bind( {} );
@@ -80,7 +122,7 @@ WithAnSVG.args = {
 };
 
 /**
- * Although it's preferred to use icons from the `@wordpress/icons` package, Dashicons are still supported,
+ * Although it's preferred to use icons from the `@wordpress/icons` package, [Dashicons](https://developer.wordpress.org/resource/dashicons/) are still supported,
  * as long as you are in a context where the Dashicons stylesheet is loaded. To simulate that here,
  * use the Global CSS Injector in the Storybook toolbar at the top and select the "WordPress" preset.
  */

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

@@ -16,7 +16,8 @@ import { InputControlSuffixWrapper } from '../input-suffix-wrapper';
 import Button from '../../button';
 
 const meta: Meta< typeof InputControl > = {
-	title: 'Components (Experimental)/InputControl',
+	title: 'Components (Experimental)/Selection & Input/InputControl',
+	id: 'components-experimental-inputcontrol',
 	component: InputControl,
 	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
 	subcomponents: { InputControlPrefixWrapper, InputControlSuffixWrapper },

package/src/menu/styles.ts

@@ -380,7 +380,7 @@ export const MenuItemHelpText = styled( Truncate )`
 	font-size: ${ font( 'helpText.fontSize' ) };
 	line-height: 16px;
 	color: ${ LIGHTER_TEXT_COLOR };
-	word-break: break-all;
+	overflow-wrap: anywhere;
 
 	[data-active-item]:not( [data-focus-visible] )
 		*:not( ${ MenuPopoverInnerWrapper } )

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

@@ -16,8 +16,9 @@ import MenuItemsChoice from '../../menu-items-choice';
 import type { Meta, StoryFn } from '@storybook/react';
 
 const meta: Meta< typeof MenuGroup > = {
-	title: 'Components/MenuGroup',
+	title: 'Components/Actions/MenuGroup',
 	component: MenuGroup,
+	id: 'components-menugroup',
 	argTypes: {
 		children: { control: { type: null } },
 	},

package/src/menu-item/stories/index.story.tsx

@@ -17,7 +17,8 @@ import Shortcut from '../../shortcut';
 
 const meta: Meta< typeof MenuItem > = {
 	component: MenuItem,
-	title: 'Components/MenuItem',
+	title: 'Components/Actions/MenuItem',
+	id: 'components-menuitem',
 	argTypes: {
 		children: { control: { type: null } },
 		icon: {

package/src/menu-items-choice/stories/index.story.tsx

@@ -16,7 +16,8 @@ import MenuGroup from '../../menu-group';
 
 const meta: Meta< typeof MenuItemsChoice > = {
 	component: MenuItemsChoice,
-	title: 'Components/MenuItemsChoice',
+	title: 'Components/Actions/MenuItemsChoice',
+	id: 'components-menuitemschoice',
 	argTypes: {
 		onHover: { action: 'onHover' },
 		onSelect: { action: 'onSelect' },

package/src/modal/index.tsx

@@ -335,10 +335,10 @@ function UnforwardedModal(
 									<>
 										<Spacer
 											marginBottom={ 0 }
-											marginLeft={ 3 }
+											marginLeft={ 2 }
 										/>
 										<Button
-											size="small"
+											size="compact"
 											onClick={ (
 												event: React.MouseEvent< HTMLButtonElement >
 											) =>

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

@@ -111,7 +111,7 @@ export const WithHeaderActions: StoryFn< typeof Modal > = Template.bind( {} );
 WithHeaderActions.args = {
 	...Default.args,
 	headerActions: (
-		<Button icon={ fullscreen } label="Fullscreen mode" size="small" />
+		<Button icon={ fullscreen } label="Fullscreen mode" size="compact" />
 	),
 	children: <div style={ { height: '200px' } } />,
 };

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

@@ -14,7 +14,8 @@ import { useState } from '@wordpress/element';
 import NumberControl from '..';
 
 const meta: Meta< typeof NumberControl > = {
-	title: 'Components (Experimental)/NumberControl',
+	title: 'Components (Experimental)/Selection & Input/NumberControl',
+	id: 'components-experimental-numbercontrol',
 	component: NumberControl,
 	argTypes: {
 		onChange: { action: 'onChange' },

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

@@ -45,6 +45,7 @@ const Template: StoryFn< typeof Placeholder > = ( args ) => {
 			<div>
 				<TextControl
 					__nextHasNoMarginBottom
+					__next40pxDefaultSize
 					label="Sample Field"
 					placeholder="Enter something here"
 					value={ value }

package/src/private-apis.ts

@@ -2,7 +2,6 @@
  * Internal dependencies
  */
 import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
-import { createPrivateSlotFill } from './slot-fill';
 import { Menu } from './menu';
 import { ComponentsContext } from './context/context-system-provider';
 import Theme from './theme';
@@ -13,7 +12,6 @@ import { lock } from './lock-unlock';
 export const privateApis = {};
 lock( privateApis, {
 	__experimentalPopoverLegacyPositionToPlacement,
-	createPrivateSlotFill,
 	ComponentsContext,
 	Tabs,
 	Theme,

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

@@ -15,7 +15,8 @@ import RadioControl from '..';
 
 const meta: Meta< typeof RadioControl > = {
 	component: RadioControl,
-	title: 'Components/RadioControl',
+	title: 'Components/Selection & Input/Common/RadioControl',
+	id: 'components-radiocontrol',
 	argTypes: {
 		onChange: {
 			action: 'onChange',

package/src/range-control/README.md

@@ -88,9 +88,10 @@ import { RangeControl } from '@wordpress/components';
 const MyRangeControl = () => {
 	const [ columns, setColumns ] = useState( 2 );
 
-	return(
+	return (
 		<RangeControl
 			__nextHasNoMarginBottom
+			__next40pxDefaultSize
 			label="Columns"
 			value={ columns }
 			onChange={ ( value ) => setColumns( value ) }
@@ -153,7 +154,6 @@ Disables the `input`, preventing new values from being applied.
 -   Required: No
 -   Platform: Web
 
-
 ### `help`: `string|Element`
 
 If this property is added, a help text will be generated using help property as the content.
@@ -165,7 +165,7 @@ If this property is added, a help text will be generated using help property as
 
 Provides control over whether the label will only be visible to screen readers.
 
-- Required: No
+-   Required: No
 
 ### `icon`: `string`
 
@@ -334,6 +334,7 @@ The minimum amount by which `value` changes. It is also a factor in validation a
 
 -   Required: No
 -   Platform: Web
+
 ### `trackColor`: `CSSProperties[ 'color' ]`
 
 CSS color string to customize the track element's background.

package/src/range-control/index.tsx

@@ -38,6 +38,7 @@ import {
 import type { RangeControlProps } from './types';
 import type { WordPressComponentProps } from '../context';
 import { space } from '../utils/space';
+import { maybeWarnDeprecated36pxSize } from '../utils/deprecated-36px-size';
 
 const noop = () => {};
 
@@ -96,6 +97,7 @@ function UnforwardedRangeControl(
 		trackColor,
 		value: valueProp,
 		withInputField = true,
+		__shouldNotWarnDeprecated36pxSize,
 		...otherProps
 	} = props;
 
@@ -229,6 +231,14 @@ function UnforwardedRangeControl(
 		[ isRTL() ? 'right' : 'left' ]: fillValueOffset,
 	};
 
+	// Add default size deprecation warning.
+	maybeWarnDeprecated36pxSize( {
+		componentName: 'RangeControl',
+		__next40pxDefaultSize,
+		size: undefined,
+		__shouldNotWarnDeprecated36pxSize,
+	} );
+
 	return (
 		<BaseControl
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
@@ -384,6 +394,7 @@ function UnforwardedRangeControl(
  *   return (
  *     <RangeControl
  *       __nextHasNoMarginBottom
+ *       __next40pxDefaultSize
  *       help="Please select how transparent you would like this."
  *       initialPosition={50}
  *       label="Opacity"