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

package/src/font-size-picker/font-size-picker-select.tsx

@@ -69,6 +69,7 @@ const FontSizePickerSelect = ( props: FontSizePickerSelectProps ) => {
 	return (
 		<CustomSelectControl
 			__next40pxDefaultSize={ __next40pxDefaultSize }
+			__shouldNotWarnDeprecated36pxSize
 			className="components-font-size-picker__select"
 			label={ __( 'Font size' ) }
 			hideLabelFromVision

package/src/font-size-picker/index.tsx

@@ -212,6 +212,7 @@ const UnforwardedFontSizePicker = (
 						<FlexItem isBlock>
 							<UnitControl
 								__next40pxDefaultSize={ __next40pxDefaultSize }
+								__shouldNotWarnDeprecated36pxSize
 								label={ __( 'Custom' ) }
 								labelPosition="top"
 								hideLabelFromVision

package/src/font-size-picker/stories/index.story.tsx

@@ -17,7 +17,7 @@ const meta: Meta< typeof FontSizePicker > = {
 	title: 'Components/FontSizePicker',
 	component: FontSizePicker,
 	argTypes: {
-		value: { control: { type: null } },
+		value: { control: false },
 	},
 	parameters: {
 		actions: { argTypesRegex: '^on.*' },

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

@@ -1,95 +1,105 @@
 # FormFileUpload
 
-FormFileUpload is a component that allows users to select files from their local device.
+<!-- 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-formfileupload--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
+
+FormFileUpload allows users to select files from their local device.
 
 ```jsx
 import { FormFileUpload } from '@wordpress/components';
 
 const MyFormFileUpload = () => (
-	<FormFileUpload
-		accept="image/*"
-		onChange={ ( event ) => console.log( event.currentTarget.files ) }
-	>
-		Upload
-	</FormFileUpload>
+  <FormFileUpload
+    __next40pxDefaultSize
+    accept="image/*"
+    onChange={ ( event ) => console.log( event.currentTarget.files ) }
+  >
+    Upload
+  </FormFileUpload>
 );
 ```
-
 ## Props
 
-The component accepts the following props. Props not included in this set will be passed to the `Button` component.
+### `__next40pxDefaultSize`
+
+Start opting into the larger default height that will become the default size in a future version.
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-### accept
+### `accept`
 
-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/*`.
-More information about this string is available in 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/*`.
 
--   Type: `String`
--   Required: No
+ - Type: `string`
+ - Required: No
 
-### children
+### `children`
 
 Children are passed as children of `Button`.
 
--   Type: `Boolean`
--   Required: No
+ - Type: `ReactNode`
+ - Required: No
 
-### icon
+### `icon`
 
-The icon to render. Supported values are: Dashicons (specified as strings), functions, Component instances and `null`.
+The icon to render in the default button.
 
--   Type: `String|Function|Component|null`
--   Required: No
--   Default: `null`
+See the `Icon` component docs for more information.
 
-### multiple
+ - Type: `IconType`
+ - Required: No
+
+### `multiple`
 
 Whether to allow multiple selection of files or not.
 
--   Type: `Boolean`
--   Required: No
--   Default: `false`
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-### onChange
+### `onChange`
 
 Callback function passed directly to the `input` file element.
 
 Select files will be available in `event.currentTarget.files`.
 
--   Type: `Function`
--   Required: Yes
+ - Type: `ChangeEventHandler<HTMLInputElement>`
+ - Required: Yes
 
-### onClick
+### `onClick`
 
 Callback function passed directly to the `input` file element.
 
-This can be useful when you want to force a `change` event to fire when the user chooses the same file again. To do this, set the target value to an empty string in the `onClick` function.
+This can be useful when you want to force a `change` event to fire when
+the user chooses the same file again. To do this, set the target value to
+an empty string in the `onClick` function.
 
 ```jsx
 <FormFileUpload
-	onClick={ ( event ) => ( event.target.value = '' ) }
-	onChange={ onChange }
+  __next40pxDefaultSize
+  onClick={ ( event ) => ( event.target.value = '' ) }
+  onChange={ onChange }
 >
-	Upload
+  Upload
 </FormFileUpload>
 ```
 
--   Type: `Function`
--   Required: No
-
-### render
+ - Type: `MouseEventHandler<HTMLInputElement>`
+ - 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.
+### `render`
 
--   Type: `Function`
--   Required: No
+Optional callback function used to render the UI.
 
-### __next40pxDefaultSize
-
-Start opting into the larger default height that will become the default size in a future version.
+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: `Boolean`
--   Required: No
--   Default: `false`
+ - Type: `(arg: { openFileDialog: () => void; }) => ReactNode`
+ - Required: No

package/src/form-file-upload/docs-manifest.json

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

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,