@wordpress/components 28.13.1-next.082ed6819.0 → 29.0.1-next.a9f418477.0

package/src/form-file-upload/index.tsx

@@ -9,15 +9,17 @@ import { useRef } from '@wordpress/element';
 import Button from '../button';
 import type { WordPressComponentProps } from '../context';
 import type { FormFileUploadProps } from './types';
+import { maybeWarnDeprecated36pxSize } from '../utils/deprecated-36px-size';
 
 /**
- * FormFileUpload is a component that allows users to select files from their local device.
+ * FormFileUpload allows users to select files from their local device.
  *
  * ```jsx
  * import { FormFileUpload } from '@wordpress/components';
  *
  * const MyFormFileUpload = () => (
  *   <FormFileUpload
+ *     __next40pxDefaultSize
  *     accept="image/*"
  *     onChange={ ( event ) => console.log( event.currentTarget.files ) }
  *   >
@@ -40,6 +42,15 @@ export function FormFileUpload( {
 		ref.current?.click();
 	};
 
+	if ( ! render ) {
+		maybeWarnDeprecated36pxSize( {
+			componentName: 'FormFileUpload',
+			__next40pxDefaultSize: props.__next40pxDefaultSize,
+			// @ts-expect-error - We don't "officially" support all Button props but this likely happens.
+			size: props.size,
+		} );
+	}
+
 	const ui = render ? (
 		render( { openFileDialog } )
 	) : (

package/src/form-file-upload/stories/index.story.tsx

@@ -18,9 +18,9 @@ const meta: Meta< typeof FormFileUpload > = {
 	id: 'components-formfileupload',
 	component: FormFileUpload,
 	argTypes: {
-		icon: { control: { type: null } },
-		onChange: { action: 'onChange', control: { type: null } },
-		onClick: { control: { type: null } },
+		icon: { control: false },
+		onChange: { action: 'onChange', control: false },
+		onClick: { control: false },
 	},
 	parameters: {
 		controls: { expanded: true },
@@ -36,6 +36,7 @@ const Template: StoryFn< typeof FormFileUpload > = ( props ) => {
 export const Default = Template.bind( {} );
 Default.args = {
 	children: 'Select file',
+	__next40pxDefaultSize: true,
 };
 
 export const RestrictFileTypes = Template.bind( {} );

package/src/form-file-upload/test/index.tsx

@@ -7,13 +7,17 @@ import userEvent from '@testing-library/user-event';
 /**
  * Internal dependencies
  */
-import FormFileUpload from '..';
+import _FormFileUpload from '..';
 
 /**
  * Browser dependencies
  */
 const { File } = window;
 
+const FormFileUpload = (
+	props: React.ComponentProps< typeof _FormFileUpload >
+) => <_FormFileUpload __next40pxDefaultSize { ...props } />;
+
 // @testing-library/user-event considers changing <input type="file"> to a string as a change, but it do not occur on real browsers, so the comparisons will be against this result
 const fakePath = expect.objectContaining( {
 	target: expect.objectContaining( {

package/src/form-file-upload/types.ts

@@ -17,10 +17,9 @@ export type FormFileUploadProps = {
 	 */
 	__next40pxDefaultSize?: boolean;
 	/**
-	 * A string passed to `input` element that tells the browser which file types can be
-	 * upload to the upload by the user use. e.g: `image/*,video/*`.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#Unique_file_type_specifiers.
+	 * 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/*`.
 	 */
 	accept?: InputHTMLAttributes< HTMLInputElement >[ 'accept' ];
 	/**
@@ -28,7 +27,9 @@ export type FormFileUploadProps = {
 	 */
 	children?: ReactNode;
 	/**
-	 * The icon to render in the `Button`.
+	 * The icon to render in the default button.
+	 *
+	 * See the `Icon` component docs for more information.
 	 */
 	icon?: ComponentProps< typeof Icon >[ 'icon' ];
 	/**
@@ -50,10 +51,11 @@ export type FormFileUploadProps = {
 	 *
 	 * ```jsx
 	 * <FormFileUpload
-	 * 	onClick={ ( event ) => ( event.target.value = '' ) }
-	 * 	onChange={ onChange }
+	 *   __next40pxDefaultSize
+	 *   onClick={ ( event ) => ( event.target.value = '' ) }
+	 *   onChange={ onChange }
 	 * >
-	 * 	Upload
+	 *   Upload
 	 * </FormFileUpload>
 	 * ```
 	 */

package/src/form-token-field/README.md

@@ -85,6 +85,7 @@ const MyFormTokenField = () => {
 
 	return (
 		<FormTokenField
+			__next40pxDefaultSize
 			value={ selectedContinents }
 			suggestions={ continents }
 			onChange={ ( tokens ) => setSelectedContinents( tokens ) }

package/src/form-token-field/index.tsx

@@ -30,6 +30,7 @@ import {
 import { Spacer } from '../spacer';
 import { useDeprecated36pxDefaultSizeProp } from '../utils/use-deprecated-props';
 import { withIgnoreIMEEvents } from '../utils/with-ignore-ime-events';
+import { maybeWarnDeprecated36pxSize } from '../utils/deprecated-36px-size';
 
 const identity = ( value: string ) => value;
 
@@ -86,6 +87,12 @@ export function FormTokenField( props: FormTokenFieldProps ) {
 		} );
 	}
 
+	maybeWarnDeprecated36pxSize( {
+		componentName: 'FormTokenField',
+		size: undefined,
+		__next40pxDefaultSize,
+	} );
+
 	const instanceId = useInstanceId( FormTokenField );
 
 	// We reset to these initial values again in the onBlur

package/src/form-token-field/stories/index.story.tsx

@@ -19,10 +19,10 @@ const meta: Meta< typeof FormTokenField > = {
 	id: 'components-formtokenfield',
 	argTypes: {
 		value: {
-			control: { type: null },
+			control: false,
 		},
 		__experimentalValidateInput: {
-			control: { type: null },
+			control: false,
 		},
 	},
 	parameters: {
@@ -64,6 +64,7 @@ Default.args = {
 	label: 'Type a continent',
 	suggestions: continents,
 	__nextHasNoMarginBottom: true,
+	__next40pxDefaultSize: true,
 };
 
 export const Async: StoryFn< typeof FormTokenField > = ( {
@@ -102,6 +103,7 @@ Async.args = {
 	label: 'Type a continent',
 	suggestions: continents,
 	__nextHasNoMarginBottom: true,
+	__next40pxDefaultSize: true,
 };
 
 export const DropdownSelector: StoryFn< typeof FormTokenField > =

package/src/form-token-field/test/index.tsx

@@ -21,7 +21,11 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import FormTokenField from '../';
+import _FormTokenField from '../';
+
+const FormTokenField = ( props: ComponentProps< typeof _FormTokenField > ) => (
+	<_FormTokenField __next40pxDefaultSize { ...props } />
+);
 
 const FormTokenFieldWithState = ( {
 	onChange,

package/src/gradient-picker/README.md

@@ -100,6 +100,14 @@ gradients from `gradients` will be shown.
  - Required: No
  - Default: `false`
 
+### `enableAlpha`
+
+Whether to enable alpha transparency options in the picker.
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `true`
+
 ### `gradients`
 
 An array of objects as predefined gradients displayed above the gradient

package/src/gradient-picker/index.tsx

@@ -213,6 +213,7 @@ export function GradientPicker( {
 	onChange,
 	value,
 	clearable = true,
+	enableAlpha = true,
 	disableCustomGradients = false,
 	__experimentalIsRenderedInSidebar,
 	headingLevel = 2,
@@ -230,6 +231,7 @@ export function GradientPicker( {
 					__experimentalIsRenderedInSidebar={
 						__experimentalIsRenderedInSidebar
 					}
+					enableAlpha={ enableAlpha }
 					value={ value }
 					onChange={ onChange }
 				/>

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

@@ -22,7 +22,7 @@ const meta: Meta< typeof GradientPicker > = {
 		actions: { argTypesRegex: '^on.*' },
 	},
 	argTypes: {
-		value: { control: { type: null } },
+		value: { control: false },
 	},
 };
 export default meta;

package/src/gradient-picker/types.ts

@@ -56,6 +56,12 @@ type GradientPickerBaseProps = {
 	 * @default true
 	 */
 	loop?: boolean;
+	/**
+	 * Whether to enable alpha transparency options in the picker.
+	 *
+	 * @default true
+	 */
+	enableAlpha?: boolean;
 } & (
 	| {
 			// TODO: [#54055] Either this or `aria-labelledby` should be required

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

@@ -15,7 +15,7 @@ const meta: Meta< typeof Grid > = {
 	argTypes: {
 		as: { control: { type: 'text' } },
 		align: { control: { type: 'text' } },
-		children: { control: { type: null } },
+		children: { control: false },
 		columnGap: { control: { type: 'text' } },
 		columns: {
 			table: { type: { summary: 'number' } },

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

@@ -46,10 +46,10 @@ const meta: Meta< typeof HStack > = {
 	id: 'components-experimental-hstack',
 	argTypes: {
 		as: {
-			control: { type: null },
+			control: false,
 		},
 		children: {
-			control: { type: null },
+			control: false,
 		},
 		alignment: {
 			control: { type: 'select' },

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

@@ -21,11 +21,7 @@ export {
 	default as Animate,
 	getAnimateClassName as __unstableGetAnimateClassName,
 } from './animate';
-export {
-	__unstableMotion,
-	__unstableAnimatePresence,
-	__unstableMotionContext,
-} from './animation';
+export { __unstableMotion, __unstableAnimatePresence } from './animation';
 export { default as AnglePickerControl } from './angle-picker-control';
 export {
 	default as Autocomplete,

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

@@ -23,10 +23,10 @@ const meta: Meta< typeof InputControl > = {
 	subcomponents: { InputControlPrefixWrapper, InputControlSuffixWrapper },
 	argTypes: {
 		__unstableInputWidth: { control: { type: 'text' } },
-		__unstableStateReducer: { control: { type: null } },
-		onChange: { control: { type: null } },
-		prefix: { control: { type: null } },
-		suffix: { control: { type: null } },
+		__unstableStateReducer: { control: false },
+		onChange: { control: false },
+		prefix: { control: false },
+		suffix: { control: false },
 		type: { control: { type: 'text' } },
 		value: { control: { disable: true } },
 	},

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

@@ -17,8 +17,8 @@ const meta: Meta< typeof ItemGroup > = {
 	subcomponents: { Item },
 	title: 'Components (Experimental)/ItemGroup',
 	argTypes: {
-		as: { control: { type: null } },
-		children: { control: { type: null } },
+		as: { control: false },
+		children: { control: false },
 	},
 	parameters: {
 		controls: { expanded: true },

package/src/menu/checkbox-item.tsx

@@ -16,30 +16,32 @@ import type { WordPressComponentProps } from '../context';
 import { MenuContext } from './context';
 import type { MenuCheckboxItemProps } from './types';
 import * as Styled from './styles';
-import { useTemporaryFocusVisibleFix } from './use-temporary-focus-visible-fix';
 
 export const MenuCheckboxItem = forwardRef<
 	HTMLDivElement,
 	WordPressComponentProps< MenuCheckboxItemProps, 'div', false >
 >( function MenuCheckboxItem(
-	{ suffix, children, onBlur, hideOnClick = false, ...props },
+	{ suffix, children, hideOnClick = false, ...props },
 	ref
 ) {
-	// TODO: Remove when https://github.com/ariakit/ariakit/issues/4083 is fixed
-	const focusVisibleFixProps = useTemporaryFocusVisibleFix( { onBlur } );
 	const menuContext = useContext( MenuContext );
 
+	if ( ! menuContext?.store ) {
+		throw new Error(
+			'Menu.CheckboxItem can only be rendered inside a Menu component'
+		);
+	}
+
 	return (
 		<Styled.MenuCheckboxItem
 			ref={ ref }
 			{ ...props }
-			{ ...focusVisibleFixProps }
 			accessibleWhenDisabled
 			hideOnClick={ hideOnClick }
-			store={ menuContext?.store }
+			store={ menuContext.store }
 		>
 			<Ariakit.MenuItemCheck
-				store={ menuContext?.store }
+				store={ menuContext.store }
 				render={ <Styled.ItemPrefixWrapper /> }
 				// Override some ariakit inline styles
 				style={ { width: 'auto', height: 'auto' } }

package/src/menu/group-label.tsx

@@ -17,6 +17,13 @@ export const MenuGroupLabel = forwardRef<
 	WordPressComponentProps< MenuGroupLabelProps, 'div', false >
 >( function MenuGroup( props, ref ) {
 	const menuContext = useContext( MenuContext );
+
+	if ( ! menuContext?.store ) {
+		throw new Error(
+			'Menu.GroupLabel can only be rendered inside a Menu component'
+		);
+	}
+
 	return (
 		<Styled.MenuGroupLabel
 			ref={ ref }
@@ -31,7 +38,7 @@ export const MenuGroupLabel = forwardRef<
 				/>
 			}
 			{ ...props }
-			store={ menuContext?.store }
+			store={ menuContext.store }
 		/>
 	);
 } );

package/src/menu/group.tsx

@@ -16,11 +16,18 @@ export const MenuGroup = forwardRef<
 	WordPressComponentProps< MenuGroupProps, 'div', false >
 >( function MenuGroup( props, ref ) {
 	const menuContext = useContext( MenuContext );
+
+	if ( ! menuContext?.store ) {
+		throw new Error(
+			'Menu.Group can only be rendered inside a Menu component'
+		);
+	}
+
 	return (
 		<Styled.MenuGroup
 			ref={ ref }
 			{ ...props }
-			store={ menuContext?.store }
+			store={ menuContext.store }
 		/>
 	);
 } );