@wordpress/components 28.8.6 → 28.10.0

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

@@ -1,12 +1,15 @@
+<!-- This file is generated automatically and cannot be edited directly. -->
+
 # AlignmentMatrixControl
 
-AlignmentMatrixControl components enable adjustments to horizontal and vertical alignments for UI.
 
-## Usage
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-alignmentmatrixcontrol--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
+
+AlignmentMatrixControl components enable adjustments to horizontal and vertical alignments for UI.
 
 ```jsx
-import { useState } from 'react';
 import { AlignmentMatrixControl } from '@wordpress/components';
+import { useState } from '@wordpress/element';
 
 const Example = () => {
 	const [ alignment, setAlignment ] = useState( 'center center' );
@@ -14,63 +17,70 @@ const Example = () => {
 	return (
 		<AlignmentMatrixControl
 			value={ alignment }
-			onChange={ ( newAlignment ) => setAlignment( newAlignment ) }
+			onChange={ setAlignment }
 		/>
 	);
 };
 ```
-
 ## Props
 
-The component accepts the following props:
+### `defaultValue`
 
-### className
+If provided, sets the default alignment value.
 
-The class that will be added to the classes of the underlying `grid` widget.
--   Type: `string`
--   Required: No
+ - 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'`
 
-### id
+### `label`
 
-Unique ID for the component.
+Accessible label. If provided, sets the `aria-label` attribute of the
+underlying `grid` widget.
 
--  Type: `string`
--  Required: No
+ - Type: `string`
+ - Required: No
+ - Default: `'Alignment Matrix Control'`
 
-### label
+### `onChange`
 
-Accessible label. If provided, sets the `aria-label` attribute of the underlying `grid` widget.
+A function that receives the updated alignment value.
 
--   Type: `string`
--   Required: No
--   Default: `Alignment Matrix Control`
+ - Type: `(newValue: AlignmentMatrixControlValue) => void`
+ - Required: No
 
-### defaultValue
+### `value`
 
-If provided, sets the default alignment value.
+The current alignment value.
 
-- Type: `AlignmentMatrixControlValue`
-- Required: No
-- Default: `center center`
+ - Type: `"center" | "top left" | "top center" | "top right" | "center left" | "center center" | "center right" | "bottom left" | "bottom center" | "bottom right"`
+ - Required: No
 
-### value
+### `width`
 
-The current alignment value.
+If provided, sets the width of the control.
 
-- Type: `AlignmentMatrixControlValue`
-- Required: No
+ - Type: `number`
+ - Required: No
+ - Default: `92`
 
-### onChange
+## Subcomponents
 
-A function that receives the updated alignment value.
+### AlignmentMatrixControl.Icon
 
--   Type: `( newValue: AlignmentMatrixControlValue ) => void`
--   Required: No
+#### Props
 
-### width
+##### `disablePointerEvents`
 
-If provided, sets the width of the control.
+If `true`, disables pointer events on the icon.
 
- - Type: `number`
+ - Type: `boolean`
  - Required: No
- - Default: `92`
+ - Default: `true`
+
+##### `value`
+
+The current 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`

package/src/alignment-matrix-control/docs-manifest.json

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

package/src/alignment-matrix-control/types.ts

@@ -54,6 +54,8 @@ export type AlignmentMatrixControlIconProps = Pick<
 	 * component instead_
 	 *
 	 * The size of the icon.
+	 *
+	 * @deprecated
 	 * @ignore
 	 * @default 24
 	 */

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

@@ -1,44 +1,57 @@
+<!-- This file is generated automatically and cannot be edited directly. -->
+
 # AnglePickerControl
 
-`AnglePickerControl` is a React component to render a UI that allows users to pick an angle.
-Users can choose an angle in a visual UI with the mouse by dragging an angle indicator inside a circle or by directly inserting the desired angle in a text field.
 
-## Usage
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-anglepickercontrol--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
+
+`AnglePickerControl` is a React component to render a UI that allows users to
+pick an angle. Users can choose an angle in a visual UI with the mouse by
+dragging an angle indicator inside a circle or by directly inserting the
+desired angle in a text field.
 
 ```jsx
-import { useState } from 'react';
+import { useState } from '@wordpress/element';
 import { AnglePickerControl } from '@wordpress/components';
 
 function Example() {
-	const [ angle, setAngle ] = useState( 0 );
-	return (
-		<AnglePickerControl
-			value={ angle }
-			onChange={ setAngle }
-		/>
-	);
-};
+  const [ angle, setAngle ] = useState( 0 );
+  return (
+    <AnglePickerControl
+      value={ angle }
+      onChange={ setAngle }
+    </>
+  );
+}
 ```
-
 ## Props
 
-The component accepts the following props.
+### `as`
+
+The HTML element or React component to render the component as.
 
-### `label`: `string`
+ - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...`
+ - Required: No
+
+### `label`
 
 Label to use for the angle picker.
 
--   Required: No
--   Default: `__( 'Angle' )`
+ - Type: `string`
+ - Required: No
+ - Default: `__( 'Angle' )`
 
-### `value`: `number | string`
+### `onChange`
 
-The current value of the input. The value represents an angle in degrees and should be a value between 0 and 360.
+A function that receives the new value of the input.
 
--   Required: Yes
+ - Type: `(value: number) => void`
+ - Required: Yes
 
-### `onChange`: `( value: number ) => void`
+### `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.
 
--   Required: Yes
+ - Type: `string | number`
+ - Required: Yes

package/src/angle-picker-control/docs-manifest.json

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

package/src/autocomplete/index.tsx

@@ -72,6 +72,9 @@ const getNodeText = ( node: React.ReactNode ): string => {
 
 const EMPTY_FILTERED_OPTIONS: KeyedOption[] = [];
 
+// Used for generating the instance ID
+const AUTOCOMPLETE_HOOK_REFERENCE = {};
+
 export function useAutocomplete( {
 	record,
 	onChange,
@@ -79,7 +82,7 @@ export function useAutocomplete( {
 	completers,
 	contentRef,
 }: UseAutocompleteProps ) {
-	const instanceId = useInstanceId( useAutocomplete );
+	const instanceId = useInstanceId( AUTOCOMPLETE_HOOK_REFERENCE );
 	const [ selectedIndex, setSelectedIndex ] = useState( 0 );
 
 	const [ filteredOptions, setFilteredOptions ] = useState<

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

@@ -1,12 +1,7 @@
 # BorderBoxControl
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-<br />
-
-This component provides users with the ability to configure a single "flat"
-border or separate borders per side.
+An input control for the color, style, and width of the border of a box. The
+border can be customized as a whole, or individually for each side of the box.
 
 ## Development guidelines
 
@@ -28,7 +23,7 @@ show "Mixed" placeholder text.
 
 ```jsx
 import { useState } from 'react';
-import { __experimentalBorderBoxControl as BorderBoxControl } from '@wordpress/components';
+import { BorderBoxControl } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
 const colors = [
@@ -76,35 +71,35 @@ colors are organized by multiple origins.
 
 Each color may be an object containing a `name` and `color` value.
 
-- Required: No
-- Default: `[]`
+-   Required: No
+-   Default: `[]`
 
 ### `disableCustomColors`: `boolean`
 
 This toggles the ability to choose custom colors.
 
-- Required: No
+-   Required: No
 
 ### `enableAlpha`: `boolean`
 
 This controls whether the alpha channel will be offered when selecting
 custom colors.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 ### `enableStyle`: `boolean`
 
 This controls whether to support border style selections.
 
-- Required: No
-- Default: `true`
+-   Required: No
+-   Default: `true`
 
 ### `hideLabelFromVision`: `boolean`
 
 Provides control over whether the label will only be visible to screen readers.
 
-- Required: No
+-   Required: No
 
 ### `label`: `string`
 
@@ -113,7 +108,7 @@ If provided, a label will be generated using this as the content.
 _Whether it is visible only to screen readers is controlled via
 `hideLabelFromVision`._
 
-- Required: No
+-   Required: No
 
 ### `onChange`: `( value?: Object ) => void`
 
@@ -123,7 +118,7 @@ borders, or `undefined`.
 
 _Note: The will be `undefined` if a user clears all borders._
 
-- Required: Yes
+-   Required: Yes
 
 ### `popoverPlacement`: `string`
 
@@ -133,21 +128,21 @@ By default, popovers are displayed relative to the button that initiated the pop
 
 The available base placements are 'top', 'right', 'bottom', 'left'. Each of these base placements has an alignment in the form -start and -end. For example, 'right-start', or 'bottom-end'. These allow you to align the tooltip to the edges of the button, rather than centering it.
 
-- Required: No
+-   Required: No
 
 ### `popoverOffset`: `number`
 
 The space between the popover and the control wrapper.
 
-- Required: No
+-   Required: No
 
 ### `size`: `string`
 
 Size of the control.
 
-- Required: No
-- Default: `default`
-- Allowed values: `default`, `__unstable-large`
+-   Required: No
+-   Default: `default`
+-   Allowed values: `default`, `__unstable-large`
 
 ### `value`: `Object`
 
@@ -158,6 +153,7 @@ properties or a "split" border which defines the previous properties but for
 each side; `top`, `right`, `bottom`, and `left`.
 
 Examples:
+
 ```js
 const flatBorder = { color: '#72aee6', style: 'solid', width: '1px' };
 const splitBorders = {
@@ -168,11 +164,11 @@ const splitBorders = {
 };
 ```
 
-- Required: No
+-   Required: No
 
 ### `__next40pxDefaultSize`: `boolean`
 
 Start opting into the larger default height that will become the default size in a future version.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`

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

@@ -147,22 +147,11 @@ const UnconnectedBorderBoxControl = (
 };
 
 /**
- * The `BorderBoxControl` effectively has two view states. The first, a "linked"
- * view, allows configuration of a flat border via a single `BorderControl`.
- * The second, a "split" view, contains a `BorderControl` for each side
- * as well as a visualizer for the currently selected borders. Each view also
- * contains a button to toggle between the two.
- *
- * When switching from the "split" view to "linked", if the individual side
- * borders are not consistent, the "linked" view will display any border
- * properties selections that are consistent while showing a mixed state for
- * those that aren't. For example, if all borders had the same color and style
- * but different widths, then the border dropdown in the "linked" view's
- * `BorderControl` would show that consistent color and style but the "linked"
- * view's width input would show "Mixed" placeholder text.
+ * An input control for the color, style, and width of the border of a box. The
+ * border can be customized as a whole, or individually for each side of the box.
  *
  * ```jsx
- * import { __experimentalBorderBoxControl as BorderBoxControl } from '@wordpress/components';
+ * import { BorderBoxControl } from '@wordpress/components';
  * import { __ } from '@wordpress/i18n';
  *
  * const colors = [

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

@@ -16,7 +16,7 @@ import Button from '../../button';
 import { BorderBoxControl } from '../';
 
 const meta: Meta< typeof BorderBoxControl > = {
-	title: 'Components (Experimental)/BorderBoxControl',
+	title: 'Components/BorderBoxControl',
 	component: BorderBoxControl,
 	argTypes: {
 		onChange: { action: 'onChange' },
@@ -83,4 +83,5 @@ export const Default = Template.bind( {} );
 Default.args = {
 	colors,
 	label: 'Borders',
+	enableStyle: true,
 };

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

@@ -1,10 +1,6 @@
-#  BorderControl
+# BorderControl
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-<br />
-This component provides control over a border's color, style, and width.
+An input control for a border's color, style, and width.
 
 ## Development guidelines
 
@@ -21,7 +17,7 @@ a "shape" abstraction.
 
 ```jsx
 import { useState } from 'react';
-import { __experimentalBorderControl as BorderControl } from '@wordpress/components';
+import { BorderControl } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
 const colors = [
@@ -58,41 +54,41 @@ colors are organized by multiple origins.
 
 Each color may be an object containing a `name` and `color` value.
 
-- Required: No
-- Default: `[]`
+-   Required: No
+-   Default: `[]`
 
 ### `disableCustomColors`: `boolean`
 
 This toggles the ability to choose custom colors.
 
-- Required: No
+-   Required: No
 
 ### `disableUnits`: `boolean`
 
 This controls whether unit selection should be disabled.
 
-- Required: No
+-   Required: No
 
 ### `enableAlpha`: `boolean`
 
 This controls whether the alpha channel will be offered when selecting
 custom colors.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `true`
 
 ### `enableStyle`: `boolean`
 
 This controls whether to support border style selection.
 
-- Required: No
-- Default: `true`
+-   Required: No
+-   Default: `true`
 
 ### `hideLabelFromVision`: `boolean`
 
 Provides control over whether the label will only be visible to screen readers.
 
-- Required: No
+-   Required: No
 
 ### `isCompact`: `boolean`
 
@@ -100,7 +96,7 @@ This flags the `BorderControl` to render with a more compact appearance. It
 restricts the width of the control and prevents it from expanding to take up
 additional space.
 
-- Required: No
+-   Required: No
 
 ### `label`: `string`
 
@@ -109,7 +105,7 @@ If provided, a label will be generated using this as the content.
 _Whether it is visible only to screen readers is controlled via
 `hideLabelFromVision`._
 
-- Required: No
+-   Required: No
 
 ### `onChange`: `( value?: Object ) => void`
 
@@ -118,7 +114,7 @@ that selects or clears, border color, style, or width.
 
 _Note: the value may be `undefined` if a user clears all border properties._
 
-- Required: Yes
+-   Required: Yes
 
 ### `shouldSanitizeBorder`: `boolean`
 
@@ -126,23 +122,16 @@ If opted into, sanitizing the border means that if no width or color have been
 selected, the border style is also cleared and `undefined` is returned as the
 new border value.
 
-- Required: No
-- Default: true
-
-### `showDropdownHeader`: `boolean`
-
-Whether or not to render a header for the border color and style picker
-dropdown. The header includes a label for the color picker and a close button.
-
-- Required: No
+-   Required: No
+-   Default: `true`
 
 ### `size`: `string`
 
 Size of the control.
 
-- Required: No
-- Default: `default`
-- Allowed values: `default`, `__unstable-large`
+-   Required: No
+-   Default: `default`
+-   Allowed values: `default`, `__unstable-large`
 
 ### `value`: `Object`
 
@@ -150,6 +139,7 @@ An object representing a border or `undefined`. Used to set the current border
 configuration for this component.
 
 Example:
+
 ```js
  {
 	color: '#72aee6',
@@ -158,25 +148,25 @@ Example:
 }
 ```
 
-- Required: No
+-   Required: No
 
 ### `width`: `CSSProperties[ 'width' ]`
 
 Controls the visual width of the `BorderControl`. It has no effect if the
 `isCompact` prop is set to `true`.
 
-- Required: No
+-   Required: No
 
 ### `withSlider`: `boolean`
 
 Flags whether this `BorderControl` should also render a `RangeControl` for
 additional control over a border's width.
 
-- Required: No
+-   Required: No
 
 ### `__next40pxDefaultSize`: `boolean`
 
 Start opting into the larger default height that will become the default size in a future version.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`

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

@@ -91,7 +91,6 @@ const UnconnectedBorderControl = (
 								previousStyleSelection={
 									previousStyleSelection
 								}
-								showDropdownHeader={ showDropdownHeader }
 								__experimentalIsRenderedInSidebar={
 									__experimentalIsRenderedInSidebar
 								}
@@ -141,7 +140,7 @@ const UnconnectedBorderControl = (
  * a "shape" abstraction.
  *
  * ```jsx
- * import { __experimentalBorderControl as BorderControl } from '@wordpress/components';
+ * import { BorderControl } from '@wordpress/components';
  * import { __ } from '@wordpress/i18n';
  *
  * const colors = [

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

@@ -7,7 +7,6 @@ import type { CSSProperties } from 'react';
  * WordPress dependencies
  */
 import { __, sprintf } from '@wordpress/i18n';
-import { closeSmall } from '@wordpress/icons';
 
 /**
  * Internal dependencies
@@ -17,12 +16,10 @@ import Button from '../../button';
 import ColorIndicator from '../../color-indicator';
 import ColorPalette from '../../color-palette';
 import Dropdown from '../../dropdown';
-import { HStack } from '../../h-stack';
 import { VStack } from '../../v-stack';
 import type { WordPressComponentProps } from '../../context';
 import { contextConnect } from '../../context';
 import { useBorderControlDropdown } from './hook';
-import { StyledLabel } from '../../base-control/styles/base-control-styles';
 import DropdownContentWrapper from '../../dropdown/dropdown-content-wrapper';
 
 import type { ColorObject } from '../../color-palette/types';
@@ -149,7 +146,6 @@ const BorderControlDropdown = (
 		popoverContentClassName,
 		popoverControlsClassName,
 		resetButtonClassName,
-		showDropdownHeader,
 		size,
 		__unstablePopoverProps,
 		...otherProps
@@ -197,17 +193,6 @@ const BorderControlDropdown = (
 		<>
 			<DropdownContentWrapper paddingSize="medium">
 				<VStack className={ popoverControlsClassName } spacing={ 6 }>
-					{ showDropdownHeader ? (
-						<HStack>
-							<StyledLabel>{ __( 'Border color' ) }</StyledLabel>
-							<Button
-								size="small"
-								label={ __( 'Close border color' ) }
-								icon={ closeSmall }
-								onClick={ onClose }
-							/>
-						</HStack>
-					) : undefined }
 					<ColorPalette
 						className={ popoverContentClassName }
 						value={ color }
@@ -237,6 +222,7 @@ const BorderControlDropdown = (
 							onReset();
 							onClose();
 						} }
+						__next40pxDefaultSize
 					>
 						{ __( 'Reset' ) }
 					</Button>