@wordpress/components 29.0.0 → 29.1.0

package/src/alignment-matrix-control/README.md

@@ -21,47 +21,48 @@ const Example = () => {
 	);
 };
 ```
+
 ## Props
 
 ### `defaultValue`
 
-If provided, sets the default alignment value.
-
  - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
  - Required: No
  - Default: `'center center'`
 
-### `label`
+If provided, sets the default alignment value.
 
-Accessible label. If provided, sets the `aria-label` attribute of the
-underlying `grid` widget.
+### `label`
 
  - Type: `string`
  - Required: No
  - Default: `'Alignment Matrix Control'`
 
-### `onChange`
+Accessible label. If provided, sets the `aria-label` attribute of the
+underlying `grid` widget.
 
-A function that receives the updated alignment value.
+### `onChange`
 
  - Type: `(newValue: AlignmentMatrixControlValue) => void`
  - Required: No
 
-### `value`
+A function that receives the updated alignment value.
 
-The current alignment value.
+### `value`
 
  - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
  - Required: No
 
-### `width`
+The current alignment value.
 
-If provided, sets the width of the control.
+### `width`
 
  - Type: `number`
  - Required: No
  - Default: `92`
 
+If provided, sets the width of the control.
+
 ## Subcomponents
 
 ### AlignmentMatrixControl.Icon
@@ -70,16 +71,16 @@ If provided, sets the width of the control.
 
 ##### `disablePointerEvents`
 
-If `true`, disables pointer events on the icon.
-
  - Type: `boolean`
  - Required: No
  - Default: `true`
 
-##### `value`
+If `true`, disables pointer events on the icon.
 
-The current alignment value.
+##### `value`
 
  - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
  - Required: No
  - Default: `center`
+
+The current alignment value.

package/src/angle-picker-control/README.md

@@ -23,34 +23,35 @@ function Example() {
   );
 }
 ```
+
 ## Props
 
 ### `as`
 
-The HTML element or React component to render the component as.
-
  - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...`
  - Required: No
 
-### `label`
+The HTML element or React component to render the component as.
 
-Label to use for the angle picker.
+### `label`
 
  - Type: `string`
  - Required: No
  - Default: `__( 'Angle' )`
 
-### `onChange`
+Label to use for the angle picker.
 
-A function that receives the new value of the input.
+### `onChange`
 
  - Type: `(value: number) => void`
  - Required: Yes
 
-### `value`
+A function that receives the new value of the input.
 
-The current value of the input. The value represents an angle in degrees
-and should be a value between 0 and 360.
+### `value`
 
  - Type: `string | number`
  - Required: Yes
+
+The current value of the input. The value represents an angle in degrees
+and should be a value between 0 and 360.

package/src/badge/README.md

@@ -0,0 +1,24 @@
+# Badge
+
+<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->
+
+🔒 This component is locked as a [private API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-private-apis/). We do not yet recommend using this outside of the Gutenberg project.
+
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-badge--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
+
+## Props
+
+### `children`
+
+ - Type: `string`
+ - Required: Yes
+
+Text to display inside the badge.
+
+### `intent`
+
+ - Type: `"default" | "info" | "success" | "warning" | "error"`
+ - Required: No
+ - Default: `default`
+
+Badge variant.

package/src/badge/docs-manifest.json

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

package/src/badge/index.tsx

@@ -0,0 +1,67 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { info, caution, error, published } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import type { BadgeProps } from './types';
+import type { WordPressComponentProps } from '../context';
+import Icon from '../icon';
+
+function Badge( {
+	className,
+	intent = 'default',
+	children,
+	...props
+}: WordPressComponentProps< BadgeProps, 'span', false > ) {
+	/**
+	 * Returns an icon based on the badge context.
+	 *
+	 * @return The corresponding icon for the provided context.
+	 */
+	function contextBasedIcon() {
+		switch ( intent ) {
+			case 'info':
+				return info;
+			case 'success':
+				return published;
+			case 'warning':
+				return caution;
+			case 'error':
+				return error;
+			default:
+				return null;
+		}
+	}
+
+	return (
+		<span
+			className={ clsx(
+				'components-badge',
+				`is-${ intent }`,
+				intent !== 'default' && 'has-icon',
+				className
+			) }
+			{ ...props }
+		>
+			{ intent !== 'default' && (
+				<Icon
+					icon={ contextBasedIcon() }
+					size={ 16 }
+					fill="currentColor"
+					className="components-badge__icon"
+				/>
+			) }
+			<span className="components-badge__content">{ children }</span>
+		</span>
+	);
+}
+
+export default Badge;

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

@@ -0,0 +1,54 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryObj } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import Badge from '..';
+
+const meta: Meta< typeof Badge > = {
+	component: Badge,
+	title: 'Components/Containers/Badge',
+	id: 'components-badge',
+	tags: [ 'status-private' ],
+};
+
+export default meta;
+
+type Story = StoryObj< typeof meta >;
+
+export const Default: Story = {
+	args: {
+		children: 'Code is Poetry',
+	},
+};
+
+export const Info: Story = {
+	args: {
+		...Default.args,
+		intent: 'info',
+	},
+};
+
+export const Success: Story = {
+	args: {
+		...Default.args,
+		intent: 'success',
+	},
+};
+
+export const Warning: Story = {
+	args: {
+		...Default.args,
+		intent: 'warning',
+	},
+};
+
+export const Error: Story = {
+	args: {
+		...Default.args,
+		intent: 'error',
+	},
+};

package/src/badge/styles.scss

@@ -0,0 +1,49 @@
+$badge-colors: (
+	"info": #3858e9,
+	"warning": $alert-yellow,
+	"error": $alert-red,
+	"success": $alert-green,
+);
+
+.components-badge {
+	@include reset;
+
+	background-color: color-mix(in srgb, $white 90%, var(--base-color));
+	color: color-mix(in srgb, $black 50%, var(--base-color));
+	padding: 0 $grid-unit-10;
+	min-height: $grid-unit-30;
+	max-width: 100%;
+	border-radius: $radius-small;
+	font-size: $font-size-small;
+	font-weight: 400;
+	line-height: $font-line-height-small;
+	display: inline-flex;
+	align-items: center;
+	gap: 2px;
+
+	&:where(.is-default) {
+		background-color: $gray-100;
+		color: $gray-800;
+	}
+
+	&.has-icon {
+		padding-inline-start: $grid-unit-05;
+	}
+
+	// Generate color variants
+	@each $type, $color in $badge-colors {
+		&.is-#{$type} {
+			--base-color: #{$color};
+		}
+	}
+}
+
+.components-badge__icon {
+	flex-shrink: 0;
+}
+
+.components-badge__content {
+	overflow: hidden;
+	white-space: nowrap;
+	text-overflow: ellipsis;
+}

package/src/badge/test/index.tsx

@@ -0,0 +1,45 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import _Badge from '..';
+
+const testid = 'my-badge';
+const Badge = ( props: React.ComponentProps< typeof _Badge > ) => (
+	<_Badge data-testid={ testid } { ...props } />
+);
+
+describe( 'Badge', () => {
+	it( 'should render correctly with default props', () => {
+		render( <Badge>Code is Poetry</Badge> );
+		const badge = screen.getByTestId( testid );
+		expect( badge ).toBeInTheDocument();
+		expect( badge.tagName ).toBe( 'SPAN' );
+		expect( badge ).toHaveClass( 'components-badge' );
+	} );
+
+	it( 'should render as per its intent and contain an icon', () => {
+		render( <Badge intent="error">Code is Poetry</Badge> );
+		const badge = screen.getByTestId( testid );
+		expect( badge ).toHaveClass( 'components-badge', 'is-error' );
+		expect( badge ).toHaveClass( 'has-icon' );
+	} );
+
+	it( 'should combine custom className with default class', () => {
+		render( <Badge className="custom-class">Code is Poetry</Badge> );
+		const badge = screen.getByTestId( testid );
+		expect( badge ).toHaveClass( 'components-badge' );
+		expect( badge ).toHaveClass( 'custom-class' );
+	} );
+
+	it( 'should pass through additional props', () => {
+		render( <Badge data-testid="custom-badge">Code is Poetry</Badge> );
+		const badge = screen.getByTestId( 'custom-badge' );
+		expect( badge ).toHaveTextContent( 'Code is Poetry' );
+		expect( badge ).toHaveClass( 'components-badge' );
+	} );
+} );

package/src/badge/types.ts

@@ -0,0 +1,12 @@
+export type BadgeProps = {
+	/**
+	 * Badge variant.
+	 *
+	 * @default 'default'
+	 */
+	intent?: 'default' | 'info' | 'success' | 'warning' | 'error';
+	/**
+	 * Text to display inside the badge.
+	 */
+	children: string;
+};

package/src/base-control/README.md

@@ -25,71 +25,71 @@ const MyCustomTextareaControl = ({ children, ...baseProps }) => (
 	);
 );
 ```
+
 ## Props
 
 ### `__nextHasNoMarginBottom`
 
-Start opting into the new margin-free styles that will become the default in a future version.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `as`
+Start opting into the new margin-free styles that will become the default in a future version.
 
-The HTML element or React component to render the component as.
+### `as`
 
  - 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
 
-### `className`
+The HTML element or React component to render the component as.
 
+### `className`
 
  - Type: `string`
  - Required: No
 
 ### `children`
 
-The content to be displayed within the `BaseControl`.
-
  - Type: `ReactNode`
  - Required: Yes
 
+The content to be displayed within the `BaseControl`.
+
 ### `help`
 
+ - Type: `ReactNode`
+ - Required: No
+
 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.
 
- - Type: `ReactNode`
- - Required: No
-
 ### `hideLabelFromVision`
 
-If true, the label will only be visible to screen readers.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
+If true, the label will only be visible to screen readers.
+
 ### `id`
 
+ - Type: `string`
+ - Required: No
+
 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.
 
 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`.
 
- - Type: `string`
- - Required: No
-
 ### `label`
 
-If this property is added, a label will be generated using label property as the content.
-
  - Type: `ReactNode`
  - Required: No
 
+If this property is added, a label will be generated using label property as the content.
+
 ## Subcomponents
 
 ### BaseControl.VisualLabel
@@ -113,18 +113,19 @@ const MyBaseControl = () => (
 	</BaseControl>
 );
 ```
+
 #### Props
 
 ##### `as`
 
-The HTML element or React component to render the component as.
-
  - Type: `"symbol" | "object" | "label" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | ...`
  - Required: No
 
-##### `children`
+The HTML element or React component to render the component as.
 
-The content to be displayed within the `BaseControl.VisualLabel`.
+##### `children`
 
  - Type: `ReactNode`
  - Required: Yes
+
+The content to be displayed within the `BaseControl.VisualLabel`.

package/src/box-control/README.md

@@ -28,34 +28,33 @@ function Example() {
   );
 };
 ```
+
 ## Props
 
 ### `__next40pxDefaultSize`
 
-Start opting into the larger default height that will become the default size in a future version.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `allowReset`
+Start opting into the larger default height that will become the default size in a future version.
 
-If this property is true, a button to reset the box control is rendered.
+### `allowReset`
 
  - Type: `boolean`
  - Required: No
  - Default: `true`
 
-### `id`
+If this property is true, a button to reset the box control is rendered.
 
-The id to use as a base for the unique HTML id attribute of the control.
+### `id`
 
  - Type: `string`
  - Required: No
 
-### `inputProps`
+The id to use as a base for the unique HTML id attribute of the control.
 
-Props for the internal `UnitControl` components.
+### `inputProps`
 
  - Type: `UnitControlPassthroughProps`
  - Required: No
@@ -63,25 +62,41 @@ Props for the internal `UnitControl` components.
     	min: 0,
     }`
 
-### `label`
+Props for the internal `UnitControl` components.
 
-Heading label for the control.
+### `label`
 
  - Type: `string`
  - Required: No
  - Default: `__( 'Box Control' )`
 
-### `onChange`
+Heading label for the control.
 
-A callback function when an input value changes.
+### `onChange`
 
  - Type: `(next: BoxControlValue) => void`
  - Required: No
  - Default: `() => {}`
 
-### `resetValues`
+A callback function when an input value changes.
 
-The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
+### `presets`
+
+ - Type: `Preset[]`
+ - Required: No
+
+Available presets to pick from.
+
+### `presetKey`
+
+ - Type: `string`
+ - Required: No
+
+The key of the preset to apply.
+If you provide a list of presets, you must provide a preset key to use.
+The format of preset selected values is going to be `var:preset|${ presetKey }|${ presetSlug }`
+
+### `resetValues`
 
  - Type: `BoxControlValue`
  - Required: No
@@ -92,35 +107,37 @@ The `top`, `right`, `bottom`, and `left` box dimension values to use when the co
     	left: undefined,
     }`
 
+The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
+
 ### `sides`
 
+ - Type: `readonly (keyof BoxControlValue | "horizontal" | "vertical")[]`
+ - Required: No
+
 Collection of sides to allow control of. If omitted or empty, all sides will be available.
 
 Allowed values are "top", "right", "bottom", "left", "vertical", and "horizontal".
 
- - Type: `readonly (keyof BoxControlValue | "horizontal" | "vertical")[]`
- - Required: No
-
 ### `splitOnAxis`
 
-If this property is true, when the box control is unlinked, vertical and horizontal controls
-can be used instead of updating individual sides.
-
  - Type: `boolean`
  - Required: No
  - Default: `false`
 
-### `units`
+If this property is true, when the box control is unlinked, vertical and horizontal controls
+can be used instead of updating individual sides.
 
-Available units to select from.
+### `units`
 
  - Type: `WPUnitControlUnit[]`
  - Required: No
  - Default: `CSS_UNITS`
 
-### `values`
+Available units to select from.
 
-The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values.
+### `values`
 
  - Type: `BoxControlValue`
  - Required: No
+
+The current values of the control, expressed as an object of `top`, `right`, `bottom`, and `left` values.

package/src/box-control/index.tsx

@@ -83,6 +83,8 @@ function BoxControl( {
 	splitOnAxis = false,
 	allowReset = true,
 	resetValues = DEFAULT_VALUES,
+	presets,
+	presetKey,
 	onMouseOver,
 	onMouseOut,
 }: BoxControlProps ) {
@@ -153,6 +155,8 @@ function BoxControl( {
 		sides,
 		values: inputValues,
 		__next40pxDefaultSize,
+		presets,
+		presetKey,
 	};
 
 	maybeWarnDeprecated36pxSize( {