@wordpress/components 28.9.0 → 28.11.0

package/src/base-control/README.md

@@ -1,8 +1,10 @@
 # BaseControl
 
-`BaseControl` is a component used to generate labels and help text for components handling user inputs.
+<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->
+
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-basecontrol--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
 
-## Usage
+`BaseControl` is a component used to generate labels and help text for components handling user inputs.
 
 ```jsx
 import { BaseControl, useBaseControlProps } from '@wordpress/components';
@@ -23,70 +25,80 @@ const MyCustomTextareaControl = ({ children, ...baseProps }) => (
 	);
 );
 ```
-
 ## Props
 
-The component accepts the following props:
+### `__nextHasNoMarginBottom`
 
-### id
+Start opting into the new margin-free styles that will become the default in a future version.
 
-The HTML `id` of the control element (passed in as a child to `BaseControl`) to which labels and help text are being generated. This is necessary to accessibly associate the label with that element.
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-The recommended way is to use the `useBaseControlProps` hook, which takes care of generating a unique `id` for you. Otherwise, if you choose to pass an explicit `id` to this prop, you are responsible for ensuring the uniqueness of the `id`.
+### `as`
 
--   Type: `String`
--   Required: No
+The HTML element or React component to render the component as.
 
-### label
+ - Type: `"symbol" | "object" | "label" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 516 more ... | ("view" & FunctionComponent<...>)`
+ - Required: No
 
-If this property is added, a label will be generated using label property as the content.
+### `className`
 
--   Type: `String`
--   Required: No
 
-### hideLabelFromVision
+ - Type: `string`
+ - Required: No
 
-If true, the label will only be visible to screen readers.
+### `children`
+
+The content to be displayed within the `BaseControl`.
 
--   Type: `Boolean`
--   Required: No
+ - Type: `ReactNode`
+ - Required: Yes
 
-### help
+### `help`
 
-Additional description for the control. Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
+Additional description for the control.
 
--   Type: `ReactNode`
--   Required: No
+Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an `aria-describedby` attribute.
 
-### className
+ - Type: `ReactNode`
+ - Required: No
 
-Any other classes to add to the wrapper div.
+### `hideLabelFromVision`
 
--   Type: `String`
--   Required: No
+If true, the label will only be visible to screen readers.
 
-### children
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-The content to be displayed within the BaseControl.
+### `id`
 
--   Type: `Element`
--   Required: Yes
+The HTML `id` of the control element (passed in as a child to `BaseControl`) to which labels and help text are being generated.
+This is necessary to accessibly associate the label with that element.
 
-### __nextHasNoMarginBottom
+The recommended way is to use the `useBaseControlProps` hook, which takes care of generating a unique `id` for you.
+Otherwise, if you choose to pass an explicit `id` to this prop, you are responsible for ensuring the uniqueness of the `id`.
 
-Start opting into the new margin-free styles that will become the default in a future version.
+ - Type: `string`
+ - Required: No
 
--   Type: `Boolean`
--   Required: No
--   Default: `false`
+### `label`
 
-## BaseControl.VisualLabel
+If this property is added, a label will be generated using label property as the content.
 
-`BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+ - Type: `ReactNode`
+ - Required: No
 
-It should only be used in cases where the children being rendered inside BaseControl are already accessibly labeled, e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would otherwise use if the `label` prop was passed.
+## Subcomponents
 
-## Usage
+### BaseControl.VisualLabel
+
+`BaseControl.VisualLabel` is used to render a purely visual label inside a `BaseControl` component.
+
+It should only be used in cases where the children being rendered inside `BaseControl` are already accessibly labeled,
+e.g., a button, but we want an additional visual label for that section equivalent to the labels `BaseControl` would
+otherwise use if the `label` prop was passed.
 
 ```jsx
 import { BaseControl } from '@wordpress/components';
@@ -101,19 +113,18 @@ const MyBaseControl = () => (
 	</BaseControl>
 );
 ```
+#### Props
 
-### Props
-
-#### className
+##### `as`
 
-Any other classes to add to the wrapper div.
+The HTML element or React component to render the component as.
 
--   Type: `String`
--   Required: No
+ - Type: `"symbol" | "object" | "label" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | ...`
+ - Required: No
 
-#### children
+##### `children`
 
 The content to be displayed within the `BaseControl.VisualLabel`.
 
--   Type: `Element`
--   Required: Yes
+ - Type: `ReactNode`
+ - Required: Yes

package/src/base-control/docs-manifest.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "../../schemas/docs-manifest.json",
+	"displayName": "BaseControl",
+	"filePath": "./index.tsx",
+	"subcomponents": [
+		{
+			"displayName": "VisualLabel",
+			"preferredDisplayName": "BaseControl.VisualLabel",
+			"filePath": "./index.tsx"
+		}
+	]
+}

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

@@ -12,6 +12,10 @@ import Button from '../../button';
 const meta: Meta< typeof BaseControl > = {
 	title: 'Components/BaseControl',
 	component: BaseControl,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'BaseControl.VisualLabel': BaseControl.VisualLabel,
+	},
 	argTypes: {
 		children: { control: { type: null } },
 		help: { control: { type: 'text' } },

package/src/base-control/types.ts

@@ -49,5 +49,8 @@ export type BaseControlProps = {
 };
 
 export type BaseControlVisualLabelProps = {
+	/**
+	 * The content to be displayed within the `BaseControl.VisualLabel`.
+	 */
 	children: ReactNode;
 };

package/src/border-box-control/border-box-control/README.md

@@ -47,6 +47,7 @@ const MyBorderBoxControl = () => {
 
 	return (
 		<BorderBoxControl
+			__next40pxDefaultSize
 			colors={ colors }
 			label={ __( 'Borders' ) }
 			onChange={ onChange }

package/src/border-box-control/border-box-control/component.tsx

@@ -175,6 +175,7 @@ const UnconnectedBorderBoxControl = (
  *
  * 	return (
  * 		<BorderBoxControl
+ * 			__next40pxDefaultSize
  * 			colors={ colors }
  * 			label={ __( 'Borders' ) }
  * 			onChange={ onChange }

package/src/border-box-control/border-box-control/hook.ts

@@ -19,6 +19,7 @@ import {
 import type { WordPressComponentProps } from '../../context';
 import { useContextSystem } from '../../context';
 import { useCx } from '../../utils/hooks/use-cx';
+import { maybeWarnDeprecated36pxSize } from '../../utils/deprecated-36px-size';
 
 import type { Border } from '../../border-control/types';
 import type { Borders, BorderSide, BorderBoxControlProps } from '../types';
@@ -39,6 +40,12 @@ export function useBorderBoxControl(
 		...otherProps
 	} = useContextSystem( props, 'BorderBoxControl' );
 
+	maybeWarnDeprecated36pxSize( {
+		componentName: 'BorderBoxControl',
+		__next40pxDefaultSize,
+		size,
+	} );
+
 	const computedSize =
 		size === 'default' && __next40pxDefaultSize ? '__unstable-large' : size;
 

package/src/border-box-control/stories/index.story.tsx

@@ -84,4 +84,5 @@ Default.args = {
 	colors,
 	label: 'Borders',
 	enableStyle: true,
+	__next40pxDefaultSize: true,
 };

package/src/border-box-control/test/index.tsx

@@ -44,6 +44,7 @@ const props = {
 		props.value = newValue;
 	} ),
 	value: undefined,
+	__next40pxDefaultSize: true,
 };
 
 const toggleLabelRegex = /Border color( and style)* picker/;

package/src/border-control/border-control/README.md

@@ -30,6 +30,7 @@ const MyBorderControl = () => {
 
 	return (
 		<BorderControl
+			__next40pxDefaultSize
 			colors={ colors }
 			label={ __( 'Border' ) }
 			onChange={ setBorder }

package/src/border-control/border-control/component.tsx

@@ -154,6 +154,7 @@ const UnconnectedBorderControl = (
  *
  * 	return (
  * 		<BorderControl
+ * 			__next40pxDefaultSize
  * 			colors={ colors }
  * 			label={ __( 'Border' ) }
  * 			onChange={ onChange }

package/src/border-control/border-control/hook.ts

@@ -11,8 +11,8 @@ import { parseQuantityAndUnitFromRawValue } from '../../unit-control/utils';
 import type { WordPressComponentProps } from '../../context';
 import { useContextSystem } from '../../context';
 import { useCx } from '../../utils/hooks/use-cx';
-
 import type { Border, BorderControlProps } from '../types';
+import { maybeWarnDeprecated36pxSize } from '../../utils/deprecated-36px-size';
 
 // If either width or color are defined, the border is considered valid
 // and a border style can be set as well.
@@ -41,6 +41,12 @@ export function useBorderControl(
 		...otherProps
 	} = useContextSystem( props, 'BorderControl' );
 
+	maybeWarnDeprecated36pxSize( {
+		componentName: 'BorderControl',
+		__next40pxDefaultSize,
+		size,
+	} );
+
 	const computedSize =
 		size === 'default' && __next40pxDefaultSize ? '__unstable-large' : size;
 

package/src/border-control/border-control-dropdown/component.tsx

@@ -73,15 +73,19 @@ const getToggleAriaLabel = (
 			const ariaLabelValue = getAriaLabelColorValue( colorObject.color );
 			return style
 				? sprintf(
-						// translators: %1$s: The name of the color e.g. "vivid red". %2$s: The color's hex code e.g.: "#f00:". %3$s: The current border style selection e.g. "solid".
-						'Border color and style picker. The currently selected color is called "%1$s" and has a value of "%2$s". The currently selected style is "%3$s".',
+						// translators: 1: The name of the color e.g. "vivid red". 2: The color's hex code e.g.: "#f00:". 3: The current border style selection e.g. "solid".
+						__(
+							'Border color and style picker. The currently selected color is called "%1$s" and has a value of "%2$s". The currently selected style is "%3$s".'
+						),
 						colorObject.name,
 						ariaLabelValue,
 						style
 				  )
 				: sprintf(
-						// translators: %1$s: The name of the color e.g. "vivid red". %2$s: The color's hex code e.g.: "#f00:".
-						'Border color and style picker. The currently selected color is called "%1$s" and has a value of "%2$s".',
+						// translators: 1: The name of the color e.g. "vivid red". 2: The color's hex code e.g.: "#f00:".
+						__(
+							'Border color and style picker. The currently selected color is called "%1$s" and has a value of "%2$s".'
+						),
 						colorObject.name,
 						ariaLabelValue
 				  );
@@ -91,14 +95,18 @@ const getToggleAriaLabel = (
 			const ariaLabelValue = getAriaLabelColorValue( colorValue );
 			return style
 				? sprintf(
-						// translators: %1$s: The color's hex code e.g.: "#f00:". %2$s: The current border style selection e.g. "solid".
-						'Border color and style picker. The currently selected color has a value of "%1$s". The currently selected style is "%2$s".',
+						// translators: 1: The color's hex code e.g.: "#f00:". 2: The current border style selection e.g. "solid".
+						__(
+							'Border color and style picker. The currently selected color has a value of "%1$s". The currently selected style is "%2$s".'
+						),
 						ariaLabelValue,
 						style
 				  )
 				: sprintf(
-						// translators: %1$s: The color's hex code e.g: "#f00".
-						'Border color and style picker. The currently selected color has a value of "%1$s".',
+						// translators: %s: The color's hex code e.g: "#f00".
+						__(
+							'Border color and style picker. The currently selected color has a value of "%s".'
+						),
 						ariaLabelValue
 				  );
 		}
@@ -108,8 +116,10 @@ const getToggleAriaLabel = (
 
 	if ( colorObject ) {
 		return sprintf(
-			// translators: %1$s: The name of the color e.g. "vivid red". %2$s: The color's hex code e.g: "#f00".
-			'Border color picker. The currently selected color is called "%1$s" and has a value of "%2$s".',
+			// translators: 1: The name of the color e.g. "vivid red". 2: The color's hex code e.g: "#f00".
+			__(
+				'Border color picker. The currently selected color is called "%1$s" and has a value of "%2$s".'
+			),
 			colorObject.name,
 			getAriaLabelColorValue( colorObject.color )
 		);
@@ -117,8 +127,10 @@ const getToggleAriaLabel = (
 
 	if ( colorValue ) {
 		return sprintf(
-			// translators: %1$s: The color's hex code e.g: "#f00".
-			'Border color picker. The currently selected color has a value of "%1$s".',
+			// translators: %s: The color's hex code e.g: "#f00".
+			__(
+				'Border color picker. The currently selected color has a value of "%s".'
+			),
 			getAriaLabelColorValue( colorValue )
 		);
 	}

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

@@ -93,6 +93,7 @@ export const Default = Template.bind( {} );
 Default.args = {
 	colors,
 	label: 'Border',
+	__next40pxDefaultSize: true,
 	enableAlpha: true,
 	enableStyle: true,
 	shouldSanitizeBorder: true,

package/src/border-control/test/index.js

@@ -31,6 +31,7 @@ function createProps( customProps ) {
 			props.value = newValue;
 		} ),
 		value: defaultBorder,
+		__next40pxDefaultSize: true,
 		...customProps,
 	};
 	return props;

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

@@ -22,7 +22,8 @@ import './style.css';
 import Button from '..';
 
 const meta: Meta< typeof Button > = {
-	title: 'Components/Button',
+	title: 'Components/Actions/Button',
+	id: 'components-button',
 	component: Button,
 	argTypes: {
 		// Overrides a limitation of the docgen interpreting our TS types for this as required.

package/src/button/style.scss

@@ -133,7 +133,7 @@
 	 */
 
 	&.is-secondary {
-		box-shadow: inset 0 0 0 $border-width $components-color-accent;
+		box-shadow: inset 0 0 0 $border-width $components-color-accent, 0 0 0 currentColor;
 		outline: 1px solid transparent; // Shown in high contrast mode.
 		white-space: nowrap;
 		color: $components-color-accent;
@@ -148,6 +148,10 @@
 		&[aria-disabled="true"]:hover:not(:focus) {
 			box-shadow: inset 0 0 0 $border-width $gray-300;
 		}
+
+		&:focus:not(:disabled) {
+			box-shadow: 0 0 0 currentColor inset, 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
+		}
 	}
 
 	/**

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

@@ -22,7 +22,8 @@ const meta: Meta< typeof Card > = {
 	component: Card,
 	// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
 	subcomponents: { CardHeader, CardBody, CardDivider, CardMedia, CardFooter },
-	title: 'Components/Card',
+	title: 'Components/Containers/Card',
+	id: 'components-card',
 	argTypes: {
 		as: {
 			control: { type: null },

package/src/color-palette/index.native.js

@@ -115,9 +115,8 @@ function ColorPalette( {
 				scrollViewRef.current.scrollTo( { x: 0, y: 0 } );
 			}
 		}
-		// Temporarily disabling exhuastive-deps until the component can be refactored and updated safely.
+		// Not adding additional dependencies until the component can be refactored and updated safely.
 		// Please see https://github.com/WordPress/gutenberg/pull/41253 for discussion and details.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ currentSegment ] );
 
 	function isSelectedCustom() {

package/src/color-palette/index.tsx

@@ -233,7 +233,7 @@ function UnforwardedColorPalette(
 	const displayValue = value?.replace( /^var\((.+)\)$/, '$1' );
 	const customColorAccessibleLabel = !! displayValue
 		? sprintf(
-				// translators: %1$s: The name of the color e.g: "vivid red". %2$s: The color's hex code e.g: "#f00".
+				// translators: 1: The name of the color e.g: "vivid red". 2: The color's hex code e.g: "#f00".
 				__(
 					'Custom color picker. The currently selected color is called "%1$s" and has a value of "%2$s".'
 				),

package/src/color-palette/style.scss

@@ -26,10 +26,7 @@ $border-as-box-shadow: inset 0 0 0 $border-width rgba(0, 0, 0, 0.2);
 	&::after {
 		content: "";
 		position: absolute;
-		top: 0;
-		left: 0;
-		width: 100%;
-		height: 100%;
+		inset: $border-width;
 		z-index: -1;
 		// The background image creates a checkerboard pattern. Ignore rtlcss to
 		// make it work both in LTR and RTL.
@@ -41,6 +38,7 @@ $border-as-box-shadow: inset 0 0 0 $border-width rgba(0, 0, 0, 0.2);
 		background-position: 0 0, 24px 24px;
 		/*rtl:end:ignore*/
 		background-size: calc(2 * 24px) calc(2 * 24px);
+		border-radius: $radius-medium - $border-width $radius-medium - $border-width 0 0;
 	}
 }
 

package/src/color-picker/index.native.js

@@ -111,7 +111,6 @@ function ColorPicker( {
 		// the hook’s dependencies and running it a single time. Ideally there
 		// may be a way to refactor and obviate the disabled lint rule. If not,
 		// this comment should be replaced by one that explains the reasoning.
-		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [] );
 
 	function onButtonPress( action ) {

package/src/composite/legacy/index.tsx

@@ -151,8 +151,11 @@ function proxyComposite< C extends Component >(
 
 		const { store, ...rest } =
 			mapLegacyStatePropsToComponentProps( legacyProps );
-		const props = rest as ComponentProps< C >;
-		props.id = useInstanceId( store, props.baseId, props.id );
+		let props = rest as ComponentProps< C >;
+		props = {
+			...props,
+			id: useInstanceId( store, props.baseId, props.id ),
+		};
 
 		Object.entries( propMap ).forEach( ( [ from, to ] ) => {
 			if ( props.hasOwnProperty( from ) ) {

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

@@ -16,7 +16,8 @@ import { Composite } from '..';
 import { Tooltip } from '../../tooltip';
 
 const meta: Meta< typeof Composite > = {
-	title: 'Components/Composite',
+	title: 'Components/Utilities/Composite',
+	id: 'components-composite',
 	component: Composite,
 	subcomponents: {
 		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170