@wordpress/components 28.11.0 → 28.13.0

package/src/gradient-picker/README.md

@@ -1,110 +1,148 @@
 # GradientPicker
 
-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.
+<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->
 
-![gradient-picker](https://user-images.githubusercontent.com/881729/147505438-3818c4c7-65b5-4394-b97b-af903c62adce.png)
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-gradientpicker--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
 
-## Usage
-
-Render a GradientPicker.
+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 { useState } from 'react';
 import { GradientPicker } from '@wordpress/components';
 
-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',
-				},
-			] }
-		/>
-	);
+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',
+        },
+      ] }
+    />
+  );
 };
 ```
-
 ## Props
 
-The component accepts the following props:
+### `__experimentalIsRenderedInSidebar`
 
-### `className`: `string`
+Whether this is rendered in the sidebar.
 
-The class name added to the wrapper.
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
--   Required: No
+### `asButtons`
 
-### `value`: `string`
+Whether the control should present as a set of buttons,
+each with its own tab stop.
 
-The current value of the gradient. Pass a css gradient like `linear-gradient(90deg, rgb(6, 147, 227) 0%, rgb(155, 81, 224) 100%)`. Optionally pass in a `null` value to specify no gradient is currently selected.
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
--   Required: No
--   Default: `linear-gradient(90deg, rgb(6, 147, 227) 0%, rgb(155, 81, 224) 100%)`
+### `aria-label`
 
-### `onChange`: `( currentGradient: string | undefined ) => void`
+A label to identify the purpose of the control.
 
-The function called when a new gradient has been defined. It is passed the `currentGradient` as an argument.
+ - Type: `string`
+ - Required: No
 
--   Required: Yes
+### `aria-labelledby`
 
-### `gradients`: `GradientsProp[]`
+An ID of an element to provide a label for the control.
 
-An array of objects of predefined gradients displayed above the gradient selector.
+ - Type: `string`
+ - Required: No
+
+### `className`
+
+The class name added to the wrapper.
 
--   Required: No
--   Default: `[]`
+ - Type: `string`
+ - Required: No
 
-### `clearable`: `boolean`
+### `clearable`
 
 Whether the palette should have a clearing button or not.
 
--   Required: No
--   Default: true
+ - Type: `boolean`
+ - Required: No
+ - Default: `true`
+
+### `disableCustomGradients`
+
+If true, the gradient picker will not be displayed and only defined
+gradients from `gradients` will be shown.
+
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
+
+### `gradients`
+
+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: `[]`
 
-### `disableCustomGradients`: `boolean`
+### `headingLevel`
 
-If true, the gradient picker will not be displayed and only defined gradients from `gradients` are available.
+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).
 
--   Required: No
--   Default: false
+ - Type: `1 | 2 | 3 | 4 | 5 | 6 | "1" | "2" | "3" | "4" | ...`
+ - Required: No
+ - Default: `2`
 
-### `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
+### `loop`
 
-The heading level. Only applies in cases where gradients are provided from multiple origins (ie. 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.
 
--   Required: No
--   Default: `2`
+ - Type: `boolean`
+ - Required: No
+ - Default: `true`
 
-### `asButtons`: `boolean`
+### `onChange`
 
-Whether the control should present as a set of buttons, each with its own tab stop.
+The function called when a new gradient has been defined. It is passed to
+the `currentGradient` as an argument.
 
-- Required: No
-- Default: `false`
+ - Type: `(currentGradient: string) => void`
+ - Required: Yes
 
-### `loop`: `boolean`
+### `value`
 
-Prevents keyboard interaction from wrapping around. Only used when `asButtons` is not true.
+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.
 
-- Required: No
-- Default: `true`
+ - Type: `string`
+ - Required: No
+ - Default: `'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'`

package/src/gradient-picker/docs-manifest.json

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

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/guide/page-control.tsx

@@ -27,6 +27,7 @@ export default function PageControl( {
 					aria-current={ page === currentPage ? 'step' : undefined }
 				>
 					<Button
+						size="small"
 						key={ page }
 						icon={ <PageControlIcon /> }
 						aria-label={ sprintf(

package/src/guide/style.scss

@@ -34,7 +34,7 @@
 		}
 	}
 
-	&__container {
+	.components-guide__container {
 		display: flex;
 		flex-direction: column;
 		justify-content: space-between;
@@ -42,7 +42,7 @@
 		min-height: 100%;
 	}
 
-	&__page {
+	.components-guide__page {
 		display: flex;
 		flex-direction: column;
 		justify-content: center;
@@ -53,7 +53,7 @@
 		}
 	}
 
-	&__footer {
+	.components-guide__footer {
 		align-content: center;
 		display: flex;
 		height: $button-size;
@@ -64,7 +64,7 @@
 		width: 100%;
 	}
 
-	&__page-control {
+	.components-guide__page-control {
 		margin: 0;
 		text-align: center;
 
@@ -74,8 +74,6 @@
 		}
 
 		.components-button {
-			height: 30px;
-			min-width: 20px;
 			margin: -6px 0;
 			color: $gray-200;
 		}

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

@@ -10,7 +10,8 @@ import { Heading } from '..';
 
 const meta: Meta< typeof Heading > = {
 	component: Heading,
-	title: 'Components (Experimental)/Heading',
+	title: 'Components (Experimental)/Typography/Heading',
+	id: 'components-experimental-heading',
 	argTypes: {
 		as: { control: { type: 'text' } },
 		color: { control: { type: 'color' } },

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,