From 17b0b92de8c88d13697251cd39b85b38c0c1994d Mon Sep 17 00:00:00 2001
From: Dani Guardiola <hi@daniguardio.la>
Date: Tue, 1 Oct 2024 18:10:02 +0200
Subject: [PATCH] BorderControl: Promote to stable (#65475)

* Export without experimental prefix

* Update README

* Move Storybook stories and add redirect

* Add changelog entries

* Fix changelog.

* Fix changelog (for real?)

* Fix changelog

* Apply feedback.

* Fix changelog

* Remove alpha story.

* README fix.

* Fix default in README

* Fix changelog

* Remove `showDropdownHeader` prop and the header itself.

* Added `showDropdownHeader` as deprecated.

* Remove deprecation warning

* Add ignores to jsdocs.

Co-authored-by: DaniGuardiola <daniguardiola@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
---
 packages/components/CHANGELOG.md              |  5 +-
 .../border-control-dropdown/component.tsx     | 15 -----
 .../border-control/border-control/README.md   | 62 ++++++++-----------
 .../border-control/component.tsx              |  3 +-
 .../border-control/stories/index.story.tsx    | 14 ++---
 .../src/border-control/test/index.js          | 17 +----
 .../components/src/border-control/types.ts    | 19 +++---
 packages/components/src/index.ts              |  6 +-
 storybook/manager-head.html                   |  1 +
 9 files changed, 53 insertions(+), 89 deletions(-)

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
index f98f878080aa27..3baddb5cccadd6 100644
--- a/packages/components/CHANGELOG.md
+++ b/packages/components/CHANGELOG.md
@@ -6,22 +6,21 @@
 
 -   `ToolsPanel`: atomic one-step state update when (un)registering panels ([#65564](https://github.com/WordPress/gutenberg/pull/65564)).
 -   `Navigator`: fix `isInitial` logic ([#65527](https://github.com/WordPress/gutenberg/pull/65527)).
--   `ToggleGroupControl`: Fix arrow key navigation in RTL ([#65735](https://github.com/WordPress/gutenberg/pull/65735)).
 
 ### Deprecations
 
+-   `__experimentalBorderControl` can now be imported as a stable `BorderControl` ([#65475](https://github.com/WordPress/gutenberg/pull/65475)).
 -   `__experimentalBorderBoxControl` can now be imported as a stable `BorderBoxControl` ([#65586](https://github.com/WordPress/gutenberg/pull/65586)).
 
 ### Enhancements
 
--   `Tabs`: handle horizontal overflow and large tab lists gracefully ([#64371](https://github.com/WordPress/gutenberg/pull/64371)).
+-   `BorderControl`: promote to stable ([#65475](https://github.com/WordPress/gutenberg/pull/65475)).
 -   `BorderBoxControl`: promote to stable ([#65586](https://github.com/WordPress/gutenberg/pull/65586)).
 -   `MenuGroup`: Simplify the MenuGroup styles within dropdown menus. ([#65561](https://github.com/WordPress/gutenberg/pull/65561)).
 -   `DatePicker`: Use compact button size. ([#65653](https://github.com/WordPress/gutenberg/pull/65653)).
 -   `Navigator`: add support for exit animation ([#64777](https://github.com/WordPress/gutenberg/pull/64777)).
 -   `Guide`: Update finish button to use the new default size ([#65680](https://github.com/WordPress/gutenberg/pull/65680)).
 -   `BorderControl`: Use `__next40pxDefaultSize` prop for Reset button ([#65682](https://github.com/WordPress/gutenberg/pull/65682)).
--   `Navigator`: stabilize APIs ([#64613](https://github.com/WordPress/gutenberg/pull/64613)).
 
 ## 28.8.0 (2024-09-19)
 
diff --git a/packages/components/src/border-control/border-control-dropdown/component.tsx b/packages/components/src/border-control/border-control-dropdown/component.tsx
index d84d6bea77335b..0223de66a4c78b 100644
--- a/packages/components/src/border-control/border-control-dropdown/component.tsx
+++ b/packages/components/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 }
diff --git a/packages/components/src/border-control/border-control/README.md b/packages/components/src/border-control/border-control/README.md
index 74a212d00026bd..fbd0c10e418d5a 100644
--- a/packages/components/src/border-control/border-control/README.md
+++ b/packages/components/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`
diff --git a/packages/components/src/border-control/border-control/component.tsx b/packages/components/src/border-control/border-control/component.tsx
index e2c96eaa9ffc0d..21be22c9dd55d8 100644
--- a/packages/components/src/border-control/border-control/component.tsx
+++ b/packages/components/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 = [
diff --git a/packages/components/src/border-control/stories/index.story.tsx b/packages/components/src/border-control/stories/index.story.tsx
index 9a5349d302c276..0756a18ac5c0e5 100644
--- a/packages/components/src/border-control/stories/index.story.tsx
+++ b/packages/components/src/border-control/stories/index.story.tsx
@@ -16,7 +16,7 @@ import { BorderControl } from '..';
 import type { Border } from '../types';
 
 const meta: Meta< typeof BorderControl > = {
-	title: 'Components (Experimental)/BorderControl',
+	title: 'Components/BorderControl',
 	component: BorderControl,
 	argTypes: {
 		onChange: {
@@ -93,6 +93,9 @@ export const Default = Template.bind( {} );
 Default.args = {
 	colors,
 	label: 'Border',
+	enableAlpha: true,
+	enableStyle: true,
+	shouldSanitizeBorder: true,
 };
 
 /**
@@ -133,12 +136,3 @@ WithMultipleOrigins.args = {
 	...Default.args,
 	colors: multipleOriginColors,
 };
-
-/**
- * Allow the alpha channel to be edited on each color.
- */
-export const WithAlphaEnabled = Template.bind( {} );
-WithAlphaEnabled.args = {
-	...Default.args,
-	enableAlpha: true,
-};
diff --git a/packages/components/src/border-control/test/index.js b/packages/components/src/border-control/test/index.js
index c41dce687cc522..000a89e14a40b3 100644
--- a/packages/components/src/border-control/test/index.js
+++ b/packages/components/src/border-control/test/index.js
@@ -148,19 +148,6 @@ describe( 'BorderControl', () => {
 			expect( resetButton ).toBeInTheDocument();
 		} );
 
-		it( 'should render color and style popover header', async () => {
-			const user = userEvent.setup();
-			const props = createProps( { showDropdownHeader: true } );
-			render( <BorderControl { ...props } /> );
-			await openPopover( user );
-
-			const headerLabel = screen.getByText( 'Border color' );
-			const closeButton = getButton( 'Close border color' );
-
-			expect( headerLabel ).toBeInTheDocument();
-			expect( closeButton ).toBeInTheDocument();
-		} );
-
 		it( 'should not render style options when opted out of', async () => {
 			const user = userEvent.setup();
 			const props = createProps( { enableStyle: false } );
@@ -346,10 +333,10 @@ describe( 'BorderControl', () => {
 
 		it( 'should take no action when color and style popover is closed', async () => {
 			const user = userEvent.setup();
-			const props = createProps( { showDropdownHeader: true } );
+			const props = createProps();
 			render( <BorderControl { ...props } /> );
 			await openPopover( user );
-			await user.click( getButton( 'Close border color' ) );
+			await user.keyboard( 'Escape' );
 
 			expect( props.onChange ).not.toHaveBeenCalled();
 		} );
diff --git a/packages/components/src/border-control/types.ts b/packages/components/src/border-control/types.ts
index 5e028050d8e18e..8ab614907684d2 100644
--- a/packages/components/src/border-control/types.ts
+++ b/packages/components/src/border-control/types.ts
@@ -18,12 +18,19 @@ export type Border = {
 
 export type ColorProps = Pick<
 	ColorPaletteProps,
-	'colors' | 'enableAlpha' | '__experimentalIsRenderedInSidebar'
+	'colors' | '__experimentalIsRenderedInSidebar'
 > & {
 	/**
 	 * This toggles the ability to choose custom colors.
 	 */
 	disableCustomColors?: boolean;
+	/**
+	 * This controls whether the alpha channel will be offered when selecting
+	 * custom colors.
+	 *
+	 * @default true
+	 */
+	enableAlpha?: boolean;
 };
 
 export type LabelProps = {
@@ -78,9 +85,8 @@ export type BorderControlProps = ColorProps &
 		 */
 		shouldSanitizeBorder?: boolean;
 		/**
-		 * Whether or not to show the header for the border color and style
-		 * picker dropdown. The header includes a label for the color picker
-		 * and a close button.
+		 * @deprecated This prop no longer has any effect.
+		 * @ignore
 		 */
 		showDropdownHeader?: boolean;
 		/**
@@ -139,9 +145,8 @@ export type DropdownProps = ColorProps &
 		 */
 		previousStyleSelection?: string;
 		/**
-		 * 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.
+		 * @deprecated This prop no longer has any effect.
+		 * @ignore
 		 */
 		showDropdownHeader?: boolean;
 	};
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index fe3642f7700772..69e76b0b91f43f 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -40,7 +40,11 @@ export {
 	isDefinedBorder as __experimentalIsDefinedBorder,
 	isEmptyBorder as __experimentalIsEmptyBorder,
 } from './border-box-control';
-export { BorderControl as __experimentalBorderControl } from './border-control';
+export {
+	/** @deprecated Import `BorderControl` instead. */
+	BorderControl as __experimentalBorderControl,
+	BorderControl,
+} from './border-control';
 export {
 	/** @deprecated Import `BoxControl` instead. */
 	default as __experimentalBoxControl,
diff --git a/storybook/manager-head.html b/storybook/manager-head.html
index 8525e48fffa585..dcafe36caefa72 100644
--- a/storybook/manager-head.html
+++ b/storybook/manager-head.html
@@ -3,6 +3,7 @@
 		const PREVIOUSLY_EXPERIMENTAL_COMPONENTS = [
 			'alignmentmatrixcontrol',
 			'borderboxcontrol',
+			'bordercontrol',
 			'boxcontrol',
 			'customselectcontrol-v2',
 			'dimensioncontrol',