@wordpress/components 28.5.0 → 28.7.0

package/CHANGELOG.md

@@ -2,6 +2,163 @@
 
 ## Unreleased
 
+## 28.7.0 (2024-09-05)
+
+### Deprecations
+
+-   Deprecate `replace` from the options accepted by `useNavigator().goTo()` ([#64675](https://github.com/WordPress/gutenberg/pull/64675)).
+-   Soft deprecate `size` prop on `AlignmentMatrixControl.Icon` ([#64827](https://github.com/WordPress/gutenberg/pull/64827)).
+-   `__experimentalAlignmentMatrixControl` can now be imported as a stable `AlignmentMatrixControl` ([#60913](https://github.com/WordPress/gutenberg/pull/60913)).
+-   Deprecate `DimensionControl`, scheduled to be removed in WordPress 7.0 ([#64951](https://github.com/WordPress/gutenberg/pull/64951)).
+
+### Enhancements
+
+-   `ColorPicker`: Adopt radius scale ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `CustomSelectControl V2`: Adopt radius scale ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `AlignmentMatrixControl.Icon`: rewrite entirely using SVG markup ([#64827](https://github.com/WordPress/gutenberg/pull/64827)).
+-   `DateTime`: Adopt radius scale ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `FormToggle`: Adopt radius scale ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `FormTokenField`: Remove unused border-radius ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `InputControl`: Adopt radius scale ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `Navigation`: Adopt radius scale ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `RangeControl`: Adopt radius scale ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `ResizeableBox`: Adopt radius scale ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `TabPanel`: Remove radius applied to panel focus style ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `Tabs`: Remove radius applied to panel focus style ([#64693](https://github.com/WordPress/gutenberg/pull/64693)).
+-   `UnitControl`: Update unit select styles ([#64712](https://github.com/WordPress/gutenberg/pull/64712)).
+-   `InputControl`: Add variants to prefix/suffix wrappers ([#64824](https://github.com/WordPress/gutenberg/pull/64824)).
+-   `Navigator`: remove location history, simplify internal logic ([#64675](https://github.com/WordPress/gutenberg/pull/64675)).
+-   `AlignmentMatrixControl`: Promote to stable ([#60913](https://github.com/WordPress/gutenberg/pull/60913)).
+-   Tighten gap between the main control and the prefix/suffix slot for the following components ([#64908](https://github.com/WordPress/gutenberg/pull/64908)).
+    -   `InputControl`
+    -   `NumberControl`
+    -   `SelectControl`
+    -   `TreeSelect`
+    -   `UnitControl`
+    -   Contains internal visual changes from this PR:
+        -   `AnglePickerControl`
+        -   `ColorPicker`
+-   Decrease horizontal padding from 16px to 12px on the following components, when in the 40px default size ([#64708](https://github.com/WordPress/gutenberg/pull/64708)).
+    -   `AnglePickerControl`
+    -   `ColorPicker` (on the inputs)
+    -   `CustomSelectControl`
+    -   `CustomSelectControlV2`
+    -   `DateTimePicker` (on the selects and inputs)
+    -   `DimensionControl`
+    -   `FocalPointPicker` (on the inputs)
+    -   `FontSizePicker` (on the custom inputs)
+    -   `GradientPicker` (on the selects and inputs)
+    -   `InputControl`
+    -   `NumberControl`
+    -   `QueryControls` (on the selects and inputs)
+    -   `RangeControl` (on the inputs)
+    -   `SearchControl`
+    -   `SelectControl`
+    -   `TextControl`
+    -   `TimePicker` (on the inputs)
+    -   `TreeSelect`
+    -   `UnitControl`
+-   `Modal`: Update animation effect ([#64580](https://github.com/WordPress/gutenberg/pull/64580)).
+-   `AlignmentMatrixControl`: do not use composite store directly ([#64850](https://github.com/WordPress/gutenberg/pull/64850)).
+-   `CircularOptionPicker`: do not use composite store directly ([#64833](https://github.com/WordPress/gutenberg/pull/64833)).
+
+### Bug Fixes
+
+-   `TimePicker`: use ToggleGroupControl for AM/PM toggle ([#64800](https://github.com/WordPress/gutenberg/pull/64800)).
+-   `ColorPalette` utils: do not normalize undefined color values ([#64969](https://github.com/WordPress/gutenberg/pull/64969)).
+-   `DatePicker` restore round radius for event dot ([#65031](https://github.com/WordPress/gutenberg/pull/65031)).
+
+### Internal
+
+-   `DropdownMenu` v2: expose CompositeTypeaheadV2 and CompositeHoverV2 via private APIs ([#64985](https://github.com/WordPress/gutenberg/pull/64985)).
+-   `DropdownMenu` v2: fix flashing menu item styles when using keyboard ([#64873](https://github.com/WordPress/gutenberg/pull/64873), [#64942](https://github.com/WordPress/gutenberg/pull/64942)).
+-   `DropdownMenu` v2: refactor to overloaded naming convention ([#64654](https://github.com/WordPress/gutenberg/pull/64654)).
+-   `DropdownMenu` v2: add `GroupLabel` subcomponent ([#64854](https://github.com/WordPress/gutenberg/pull/64854)).
+-   `DropdownMenuV2`: update animation ([#64868](https://github.com/WordPress/gutenberg/pull/64868)).
+-   `Composite` V2: fix Storybook docgen ([#64682](https://github.com/WordPress/gutenberg/pull/64682)).
+-   `Composite` V2: add "With Slot Fill" example ([#65051](https://github.com/WordPress/gutenberg/pull/65051)).
+-   `Composite` V2: accept store props on top-level component ([#64832](https://github.com/WordPress/gutenberg/pull/64832)).
+
+## 28.6.0 (2024-08-21)
+
+### Deprecations
+
+-   Deprecate bottom margin on the following `BaseControl`-based components. Set the `__nextHasNoMarginBottom` prop to true to start opting into the new styles, which will become the default in a future version ([#64408](https://github.com/WordPress/gutenberg/pull/64408)).
+    -   `BaseControl`
+    -   `CheckboxControl`
+    -   `ComboboxControl`
+    -   `DimensionControl`
+    -   `FocalPointPicker`
+    -   `RangeControl`
+    -   `SearchControl`
+    -   `SelectControl`
+    -   `TextControl`
+    -   `TextareaControl`
+    -   `ToggleControl`
+    -   `ToggleGroupControl`
+    -   `TreeSelect`
+-   Deprecate `NavigatorToParentButton` and `useNavigator().goToParent()` in favor of `NavigatorBackButton` and `useNavigator().goBack()` ([#63317](https://github.com/WordPress/gutenberg/pull/63317)).
+
+### Enhancements
+
+-   `Placeholder`: Temporarily rewind radius scale ([#64672](https://github.com/WordPress/gutenberg/pull/64672)).
+-   `Composite`: improve Storybook examples and add interactive controls ([#64397](https://github.com/WordPress/gutenberg/pull/64397)).
+-   `Composite`: use internal context to forward the composite store to sub-components ([#64493](https://github.com/WordPress/gutenberg/pull/64493)).
+-   `QueryControls`: Default to new 40px size ([#64457](https://github.com/WordPress/gutenberg/pull/64457)).
+-   `TimePicker`: add `hideLabelFromVision` prop ([#64267](https://github.com/WordPress/gutenberg/pull/64267)).
+-   `FocalPointPicker`: Default to new 40px size ([#64456](https://github.com/WordPress/gutenberg/pull/64456)).
+-   `DropdownMenuV2`: adopt elevation scale ([#64432](https://github.com/WordPress/gutenberg/pull/64432)).
+-   `AlignmentMatrixControl`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `AnglePickerControl`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `BorderControl`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `ButtonGroup`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Button`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `CircularOptionPicker`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `ColorIndicator`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `ColorPalette`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `CustomGradientPicker`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `DropZone`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `DropdownMenuV2`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `FocalPointPicker`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Guide`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Modal`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Placeholder`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Popover`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `ProgressBar`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `RadioControl`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Snackbar`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `TabPanel`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Text`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `ToggleGroupControl`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `ToolbarGroup`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Toolbar`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Tooltip`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `UnitControl`: Adopt radius scale ([#64368](https://github.com/WordPress/gutenberg/pull/64368)).
+-   `Popover`: allow `style` prop usage ([#64489](https://github.com/WordPress/gutenberg/pull/64489)).
+-   `ToolsPanel`: sets column-gap to 16px for ToolsPanel grid ([#64497](https://github.com/WordPress/gutenberg/pull/64497)).
+-   `Modal`: Replace references to deprecated styling variables ([#64655](https://github.com/WordPress/gutenberg/pull/64655)).
+-   `Popover`: Replace references to deprecated styling variables ([#64655](https://github.com/WordPress/gutenberg/pull/64655)).
+-   `Snackbar`: Replace references to deprecated styling variables ([#64655](https://github.com/WordPress/gutenberg/pull/64655)).
+-   `TextareaControl`: Update styles ([#64586](https://github.com/WordPress/gutenberg/pull/64586)).
+-   `CircularOptionPicker`: Update hard-coded border-width value ([#64680](https://github.com/WordPress/gutenberg/pull/64680)).
+-   `CustomGradientPicker`: Update hard-coded border-width value ([#64680](https://github.com/WordPress/gutenberg/pull/64680)).
+
+### Bug Fixes
+
+-   `RangeControl`: disable reset button when the current value is equal to the reset value ([#64579](https://github.com/WordPress/gutenberg/pull/64579)).
+-   `RangeControl`: tweak mark and label absolute positioning ([#64487](https://github.com/WordPress/gutenberg/pull/64487)).
+-   `RadioGroup`: use fieldset and legend to group radio inputs ([#64582](https://github.com/WordPress/gutenberg/pull/64582)).
+
+### Internal
+
+-   `Composite` v2: add `Hover` and `Typeahead` subcomponents ([#64399](https://github.com/WordPress/gutenberg/pull/64399)).
+-   `Composite` v2: add focus-related props to `Composite`and`Composite.Item` subcomponents ([#64450](https://github.com/WordPress/gutenberg/pull/64450)).
+-   `Composite` v2: add `Context` subcomponent ([#64493](https://github.com/WordPress/gutenberg/pull/64493)).
+-   `DropdownMenu` v2: use themed color variables ([#64647](https://github.com/WordPress/gutenberg/pull/64647)).
+-   `CustomSelectControl`: Improve type inferring ([#64412](https://github.com/WordPress/gutenberg/pull/64412)).
+-   Update `ariakit` to version `0.4.10` ([#64637](https://github.com/WordPress/gutenberg/pull/64637)).
+-   Ariakit: Use `useStoreState()` instead of `store.useState()` ([#64648](https://github.com/WordPress/gutenberg/pull/64648)).
+
 ## 28.5.0 (2024-08-07)
 
 ### Bug Fixes
@@ -17,11 +174,13 @@
 
 ### Enhancements
 
+-   `ColorPalette`: partial support of `color-mix()` CSS colors ([#64224](https://github.com/WordPress/gutenberg/pull/64224)).
 -   `TimeInput`: Expose as subcomponent of `TimePicker` ([#63145](https://github.com/WordPress/gutenberg/pull/63145)).
 -   `RadioControl`: add support for option help text ([#63751](https://github.com/WordPress/gutenberg/pull/63751)).
 -   `SelectControl`: Infer `value` type from `options` ([#64069](https://github.com/WordPress/gutenberg/pull/64069)).
 -   `Guide`: Add `__next40pxDefaultSize` to buttons ([#64181](https://github.com/WordPress/gutenberg/pull/64181)).
 -   `SelectControl`: Pass through `options` props ([#64211](https://github.com/WordPress/gutenberg/pull/64211)).
+-   `DimensionControl`: Add `__nextHasNoMarginBottom` prop to remove bottom margin ([#64346](https://github.com/WordPress/gutenberg/pull/64346)).
 
 ### Internal
 

package/CONTRIBUTING.md

@@ -6,20 +6,20 @@ The following is a set of guidelines for contributing to the `@wordpress/compone
 
 This set of guidelines should apply especially to newly introduced components. In fact, while these guidelines should also be retroactively applied to existing components, it is sometimes impossible to do so for legacy/compatibility reasons.
 
-For an example of a component that follows these requirements, take a look at [`ItemGroup`](/packages/components/src/item-group).
-- [Introducing new components](#introducing-new-components)
-- [Compatibility](#compatibility)
-- [Compound components](#compound-components)
-- [Components & Hooks](#components--hooks)
-- [TypeScript](#typescript)
-- [Styling](#styling)
-- [Context system](#context-system)
-- [Unit tests](#unit-tests)
-- [Storybook](#storybook)
-- [Documentation](#documentation)
-- [README example](#README-example)
-- [Folder structure](#folder-structure)
-- [Component versioning](#component-versioning)
+-   [Introducing new components](#introducing-new-components)
+-   [Compatibility](#compatibility)
+-   [Compound components](#compound-components)
+-   [Components & Hooks](#components--hooks)
+-   [Naming Conventions](#naming-conventions)
+-   [TypeScript](#typescript)
+-   [Styling](#styling)
+-   [Context system](#context-system)
+-   [Unit tests](#unit-tests)
+-   [Storybook](#storybook)
+-   [Documentation](#documentation)
+-   [README example](#README-example)
+-   [Folder structure](#folder-structure)
+-   [Component versioning](#component-versioning)
 
 ## Introducing new components
 
@@ -95,13 +95,13 @@ In these situations, one possible approach is to "soft-deprecate" a given legacy
 2. Updating all places in Gutenberg that use that API.
 3. Adding deprecation warnings (only after the previous point is completed, otherwise the Browser Console will be polluted by all those warnings and some e2e tests may fail).
 
-When adding new components or new props to existing components, it's recommended to prefix them with `__unstable` or `__experimental` until they're stable enough to be exposed as part of the public API.
+When adding new components or new props to existing components, it's recommended to create a [private version](/packages/private-apis/README.md)) of the component until the changes are stable enough to be exposed as part of the public API.
 
 ### Learn more
 
-- [How to preserve backward compatibility for a React Component](/docs/contributors/code/backward-compatibility.md#how-to-preserve-backward-compatibility-for-a-react-component)
-- [Experimental and Unstable APIs](/docs/contributors/code/coding-guidelines.md#experimental-and-unstable-apis)
-- [Deprecating styles](#deprecating-styles)
+-   [How to preserve backward compatibility for a React Component](/docs/contributors/code/backward-compatibility.md#how-to-preserve-backward-compatibility-for-a-react-component)
+-   [Experimental and Unstable APIs](/docs/contributors/code/coding-guidelines.md#legacy-experimental-apis-plugin-only-apis-and-private-apis)
+-   [Deprecating styles](#deprecating-styles)
 
 <!-- ## Polymorphic Components (i.e. the `as` prop)
 
@@ -121,20 +121,16 @@ When creating components that render a list of subcomponents, prefer to expose t
 ```jsx
 // ❌ Don't:
 <List
-	items={ [
-		{ value: 'Item 1' },
-		{ value: 'Item 2' },
-		{ value: 'Item 3' },
-	] }
+	items={ [ { value: 'Item 1' }, { value: 'Item 2' }, { value: 'Item 3' } ] }
 />
 ```
 
 ```jsx
 // ✅ Do:
 <List>
-	<ListItem value="Item 1" />
-	<ListItem value="Item 2" />
-	<ListItem value="Item 3" />
+	<List.Item value="Item 1" />
+	<List.Item value="Item 2" />
+	<List.Item value="Item 3" />
 </List>
 ```
 
@@ -185,25 +181,25 @@ One way to enable reusability and composition is to extract a component's underl
 
 ```tsx
 // in `hook.ts`
-function useExampleComponent( props: PolymorphicComponentProps< ExampleProps, 'div' > ) {
+function useExampleComponent(
+	props: PolymorphicComponentProps< ExampleProps, 'div' >
+) {
 	// Merge received props with the context system.
-	const { isVisible, className, ...otherProps } = useContextSystem( props, 'Example' );
+	const { isVisible, className, ...otherProps } = useContextSystem(
+		props,
+		'Example'
+	);
 
 	// Any other reusable rendering logic (e.g. computing className, state, event listeners...)
 	const cx = useCx();
 	const classes = useMemo(
-		() =>
-			cx(
-				styles.example,
-				isVisible && styles.visible,
-				className
-			),
+		() => cx( styles.example, isVisible && styles.visible, className ),
 		[ className, isVisible ]
 	);
 
 	return {
 		...otherProps,
-		className: classes
+		className: classes,
 	};
 }
 
@@ -220,8 +216,8 @@ function Example(
 
 A couple of good examples of how hooks are used for composition are:
 
-- the `Card` component, which builds on top of the `Surface` component by [calling the `useSurface` hook inside its own hook](/packages/components/src/card/card/hook.ts);
-- the `HStack` component, which builds on top of the `Flex` component and [calls the `useFlex` hook inside its own hook](/packages/components/src/h-stack/hook.tsx).
+-   the `Card` component, which builds on top of the `Surface` component by [calling the `useSurface` hook inside its own hook](/packages/components/src/card/card/hook.ts);
+-   the `HStack` component, which builds on top of the `Flex` component and [calls the `useFlex` hook inside its own hook](/packages/components/src/h-stack/hook.tsx).
 
 <!-- ## API Consinstency
 
@@ -236,6 +232,118 @@ A couple of good examples of how hooks are used for composition are:
 
 TDB -->
 
+## Naming Conventions
+
+It is recommended that compound components use dot notation to separate the namespace from the individual component names. The top-level compound component should be called the namespace (no dot notation).
+
+Dedicated React context should also use dot notation, while hooks should not.
+
+When exporting compound components and preparing them to be consumed, it is important that:
+
+-   the JSDocs appear correctly in IntelliSense;
+-   the top-level component's JSDoc appears in the Storybook docs page;
+-   the top-level and subcomponent's prop types appear correctly in the Storybook props table.
+
+To meet the above requirements, we recommend:
+
+-   using `Object.assign()` to add subcomponents as properties of the top-level component;
+-   using named functions for all components;
+-   using a separate file for each component, context and hook;
+-   setting explicitly the `displayName` on all subcomponents;
+-   adding the top-level JSDoc to the result of the `Object.assign` call;
+-   adding inline subcomponent JSDocs inside the `Object.assign` call.
+
+The following example implements all of the above recommendations.
+
+```tsx
+//=======================
+// subcomponent.tsx
+//=======================
+import { forwardRef } from '@wordpress/element';
+
+export const ComponentSubcomponent = forwardRef(
+	function UnforwardedComponentSubcomponent( props, ref ) {
+		/* ... */
+	}
+);
+
+//=======================
+// context.ts
+//=======================
+import { createContext } from '@wordpress/element';
+
+export const ComponentContext = createContext();
+
+//=======================
+// hook.ts
+//=======================
+
+/** The hook's JSDoc. */
+export function useComponent() {
+	/* ... */
+}
+
+//=======================
+// component.tsx
+//=======================
+import { forwardRef } from '@wordpress/element';
+import { ComponentSubcomponent } from './subcomponent';
+import { ComponentContext } from './context';
+
+/** The top-level component's JSDoc. */
+export const Component = Object.assign(
+	forwardRef( function UnforwardedTopLevelComponent( props, ref ) {
+		/* ... */
+	} ),
+	{
+		/** The subcomponent's JSDoc. */
+		Subcomponent: Object.assign(ComponentSubcomponent, {
+			displayName: 'Component.SubComponent';,
+		}),
+		/** The context's JSDoc. */
+		Context: Object.assign(ComponentContext, {
+			displayName: 'Component.Context'
+		}),
+	}
+);
+
+export default Component;
+
+//=======================
+// App.tsx
+//=======================
+import { Component, useComponent } from '@wordpress/components';
+import { useContext } from '@wordpress/element';
+
+function CompoundComponentExample() {
+	return (
+		<Component>
+			<Component.SubComponent />
+		</Component>
+	);
+}
+
+function ContextProviderExample() {
+	return (
+		<Component.Context.Provider value={ /* ... */ }>
+			{ /* React tree */ }
+		</Component.Context.Provider>
+	);
+}
+
+function ContextConsumerExample() {
+	const componentContext = useContext( Component.Context );
+
+	// etc
+}
+
+function HookExample() {
+	const hookReturnValue = useComponent();
+
+	// etc.
+}
+```
+
 ## TypeScript
 
 We strongly encourage using TypeScript for all new components.
@@ -278,8 +386,10 @@ function UnconnectedMyComponent(
 	//   parameter (`div` in this example)
 	// - the special `as` prop (which marks the component as polymorphic),
 	//   unless the third parameter is `false`
-	props:  WordPressComponentProps< ComponentOwnProps, 'div', true >
-) { /* ... */ }
+	props: WordPressComponentProps< ComponentOwnProps, 'div', true >
+) {
+	/* ... */
+}
 ```
 
 ### Considerations for the docgen
@@ -287,10 +397,15 @@ function UnconnectedMyComponent(
 Make sure you have a **named** export for the component, not just the default export ([example](https://github.com/WordPress/gutenberg/blob/trunk/packages/components/src/divider/component.tsx)). This ensures that the docgen can properly extract the types data. The naming should be so that the connected/forwarded component has the plain component name (`MyComponent`), and the raw component is prefixed (`UnconnectedMyComponent` or `UnforwardedMyComponent`). This makes the component's `displayName` look nicer in React devtools and in the autogenerated Storybook code snippets.
 
 ```js
-function UnconnectedMyComponent() { /* ... */ }
+function UnconnectedMyComponent() {
+	/* ... */
+}
 
 // 👇 Without this named export, the docgen will not work!
-export const MyComponent = contextConnect( UnconnectedMyComponent, 'MyComponent' );
+export const MyComponent = contextConnect(
+	UnconnectedMyComponent,
+	'MyComponent'
+);
 export default MyComponent;
 ```
 
@@ -314,16 +429,15 @@ Changing the styles of a non-experimental component must be done with care. To p
 import deprecated from '@wordpress/deprecated';
 import { Wrapper } from './styles.ts';
 
-function MyComponent({ __nextHasNoOuterMargins = false }) {
+function MyComponent( { __nextHasNoOuterMargins = false } ) {
 	if ( ! __nextHasNoOuterMargins ) {
 		deprecated( 'Outer margin styles for wp.components.MyComponent', {
 			since: '6.0',
 			version: '6.2', // Set a reasonable grace period depending on impact
-			hint:
-				'Set the `__nextHasNoOuterMargins` prop to true to start opting into the new styles, which will become the default in a future version.',
+			hint: 'Set the `__nextHasNoOuterMargins` prop to true to start opting into the new styles, which will become the default in a future version.',
 		} );
 	}
-	return <Wrapper __nextHasNoOuterMargins={__nextHasNoOuterMargins} />
+	return <Wrapper __nextHasNoOuterMargins={ __nextHasNoOuterMargins } />;
 }
 ```
 
@@ -331,7 +445,7 @@ Styles should be structured so the deprecated styles are cleanly encapsulated, a
 
 ```js
 // styles.ts
-const deprecatedMargins = ({ __nextHasNoOuterMargins }) => {
+const deprecatedMargins = ( { __nextHasNoOuterMargins } ) => {
 	if ( ! __nextHasNoOuterMargins ) {
 		return css`
 			margin: 8px;
@@ -342,7 +456,7 @@ const deprecatedMargins = ({ __nextHasNoOuterMargins }) => {
 export const Wrapper = styled.div`
 	margin: 0;
 
-	${deprecatedMargins}
+	${ deprecatedMargins }
 `;
 ```
 
@@ -358,14 +472,14 @@ Not all style changes justify a formal deprecation process. The main thing to lo
 
 ##### DOES need formal deprecation
 
-- Removing an outer margin.
-- Substantial changes to width/height, such as adding or removing a size restriction.
+-   Removing an outer margin.
+-   Substantial changes to width/height, such as adding or removing a size restriction.
 
 ##### DOES NOT need formal deprecation
 
-- Breakage only occurs in non-standard usage, such as when the consumer is overriding component internals.
-- Minor layout shifts of a few pixels.
-- Internal layout changes of a higher-level component.
+-   Breakage only occurs in non-standard usage, such as when the consumer is overriding component internals.
+-   Minor layout shifts of a few pixels.
+-   Internal layout changes of a higher-level component.
 
 ## Context system
 
@@ -373,9 +487,9 @@ The `@wordpress/components` context system is based on [React's `Context` API](h
 
 Components can use this system via a couple of functions:
 
-- they can provide values using a shared `ContextSystemProvider` component
-- they can connect to the Context via `contextConnect`
-- they can read the "computed" values from the context via `useContextSystem`
+-   they can provide values using a shared `ContextSystemProvider` component
+-   they can connect to the Context via `contextConnect`
+-   they can read the "computed" values from the context via `useContextSystem`
 
 An example of how this is used can be found in the [`Card` component family](/packages/components/src/card). For example, this is how the `Card` component injects the `size` and `isBorderless` props down to its `CardBody` subcomponent — which makes it use the correct spacing and border settings "auto-magically".
 
@@ -400,11 +514,7 @@ export function useCard( props ) {
 import { contextConnect, ContextSystemProvider } from '../../context';
 
 function Card( props, forwardedRef ) {
-	const {
-		size,
-		isBorderless,
-		...otherComputedHookProps
-	} = useCard( props );
+	const { size, isBorderless, ...otherComputedHookProps } = useCard( props );
 
 	// [...]
 
@@ -441,7 +551,10 @@ export function useCardBody( props ) {
 	// If a `CardBody` component is rendered as a child of a `Card` component, the value of
 	// the `size` prop will be the one set by the parent `Card` component via the Context
 	// System (unless the prop gets explicitely set on the `CardBody` component).
-	const { size = 'medium', ...otherDerivedProps } = useContextSystem( props, 'CardBody' );
+	const { size = 'medium', ...otherDerivedProps } = useContextSystem(
+		props,
+		'CardBody'
+	);
 
 	// [...]
 
@@ -457,7 +570,7 @@ Please refer to the [JavaScript Testing Overview docs](/docs/contributors/code/t
 
 All new components should add stories to the project's [Storybook](https://storybook.js.org/). Each [story](https://storybook.js.org/docs/react/get-started/whats-a-story) captures the rendered state of a UI component in isolation. This greatly simplifies working on a given component, while also serving as an interactive form of documentation.
 
-A component's story should be showcasing its different states — for example, the different variants of a  `Button`:
+A component's story should be showcasing its different states — for example, the different variants of a `Button`:
 
 ```jsx
 import Button from '../';
@@ -543,6 +656,7 @@ Prop description. With a new line before and after the description and before an
 Add this section when there are props that are drilled down into an internal component. See [ClipboardButton](/packages/components/src/clipboard-button/README.md) for an example.
 
 <!-- Only add the next section if the component relies on the [Context System](#context-system) -->
+
 ## Context
 
 See examples for this section for the [ItemGroup](/packages/components/src/item-group/item-group/README.md#context) and [`Card`](/packages/components/src/card/card/README.md#context) components.
@@ -601,8 +715,8 @@ As the needs of the package evolve with time, sometimes we may opt to fully rewr
 
 Here is some terminology that will be used in the upcoming sections:
 
-- "Legacy" component: the version(s) of the component that existsted on `trunk` before the rewrite;
-- API surface: the component's public APIs. It includes the list of components (and sub-components) exported from the package, their props, any associated React context. It does not include internal classnames and internal DOM structure of the components.
+-   "Legacy" component: the version(s) of the component that existsted on `trunk` before the rewrite;
+-   API surface: the component's public APIs. It includes the list of components (and subcomponents) exported from the package, their props, any associated React context. It does not include internal classnames and internal DOM structure of the components.
 
 ### Approaches
 

package/build/alignment-matrix-control/cell.js

@@ -5,11 +5,11 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = Cell;
-var _v = require("../composite/v2");
+var _composite = require("../composite");
 var _tooltip = _interopRequireDefault(require("../tooltip"));
 var _visuallyHidden = require("../visually-hidden");
 var _utils = require("./utils");
-var _alignmentMatrixControlStyles = require("./styles/alignment-matrix-control-styles");
+var _styles = require("./styles");
 var _jsxRuntime = require("react/jsx-runtime");
 /**
  * Internal dependencies
@@ -21,23 +21,20 @@ var _jsxRuntime = require("react/jsx-runtime");
 
 function Cell({
   id,
-  isActive = false,
   value,
   ...props
 }) {
-  const tooltipText = _utils.ALIGNMENT_LABEL[value];
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_tooltip.default, {
-    text: tooltipText,
-    children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_v.CompositeItem, {
+    text: _utils.ALIGNMENT_LABEL[value],
+    children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_composite.Composite.Item, {
       id: id,
-      render: /*#__PURE__*/(0, _jsxRuntime.jsx)(_alignmentMatrixControlStyles.Cell, {
+      render: /*#__PURE__*/(0, _jsxRuntime.jsx)(_styles.Cell, {
         ...props,
         role: "gridcell"
       }),
       children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_visuallyHidden.VisuallyHidden, {
         children: value
-      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_alignmentMatrixControlStyles.Point, {
-        isActive: isActive,
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_styles.Point, {
         role: "presentation"
       })]
     })

package/build/alignment-matrix-control/cell.js.map

@@ -1 +1 @@
-{"version":3,"names":["_v","require","_tooltip","_interopRequireDefault","_visuallyHidden","_utils","_alignmentMatrixControlStyles","_jsxRuntime","Cell","id","isActive","value","props","tooltipText","ALIGNMENT_LABEL","jsx","default","text","children","jsxs","CompositeItem","render","role","VisuallyHidden","Point"],"sources":["@wordpress/components/src/alignment-matrix-control/cell.tsx"],"sourcesContent":["/**\n * Internal dependencies\n */\nimport { CompositeItem } from '../composite/v2';\nimport Tooltip from '../tooltip';\nimport { VisuallyHidden } from '../visually-hidden';\n\n/**\n * Internal dependencies\n */\nimport { ALIGNMENT_LABEL } from './utils';\nimport {\n\tCell as CellView,\n\tPoint,\n} from './styles/alignment-matrix-control-styles';\nimport type { AlignmentMatrixControlCellProps } from './types';\nimport type { WordPressComponentProps } from '../context';\n\nexport default function Cell( {\n\tid,\n\tisActive = false,\n\tvalue,\n\t...props\n}: WordPressComponentProps< AlignmentMatrixControlCellProps, 'span', false > ) {\n\tconst tooltipText = ALIGNMENT_LABEL[ value ];\n\n\treturn (\n\t\t<Tooltip text={ tooltipText }>\n\t\t\t<CompositeItem\n\t\t\t\tid={ id }\n\t\t\t\trender={ <CellView { ...props } role=\"gridcell\" /> }\n\t\t\t>\n\t\t\t\t{ /* VoiceOver needs a text content to be rendered within grid cell,\n\t\t\totherwise it'll announce the content as \"blank\". So we use a visually\n\t\t\thidden element instead of aria-label. */ }\n\t\t\t\t<VisuallyHidden>{ value }</VisuallyHidden>\n\t\t\t\t<Point isActive={ isActive } role=\"presentation\" />\n\t\t\t</CompositeItem>\n\t\t</Tooltip>\n\t);\n}\n"],"mappings":";;;;;;;AAGA,IAAAA,EAAA,GAAAC,OAAA;AACA,IAAAC,QAAA,GAAAC,sBAAA,CAAAF,OAAA;AACA,IAAAG,eAAA,GAAAH,OAAA;AAKA,IAAAI,MAAA,GAAAJ,OAAA;AACA,IAAAK,6BAAA,GAAAL,OAAA;AAGkD,IAAAM,WAAA,GAAAN,OAAA;AAdlD;AACA;AACA;;AAKA;AACA;AACA;;AASe,SAASO,IAAIA,CAAE;EAC7BC,EAAE;EACFC,QAAQ,GAAG,KAAK;EAChBC,KAAK;EACL,GAAGC;AACuE,CAAC,EAAG;EAC9E,MAAMC,WAAW,GAAGC,sBAAe,CAAEH,KAAK,CAAE;EAE5C,oBACC,IAAAJ,WAAA,CAAAQ,GAAA,EAACb,QAAA,CAAAc,OAAO;IAACC,IAAI,EAAGJ,WAAa;IAAAK,QAAA,eAC5B,IAAAX,WAAA,CAAAY,IAAA,EAACnB,EAAA,CAAAoB,aAAa;MACbX,EAAE,EAAGA,EAAI;MACTY,MAAM,eAAG,IAAAd,WAAA,CAAAQ,GAAA,EAACT,6BAAA,CAAAE,IAAQ;QAAA,GAAMI,KAAK;QAAGU,IAAI,EAAC;MAAU,CAAE,CAAG;MAAAJ,QAAA,gBAKpD,IAAAX,WAAA,CAAAQ,GAAA,EAACX,eAAA,CAAAmB,cAAc;QAAAL,QAAA,EAAGP;MAAK,CAAkB,CAAC,eAC1C,IAAAJ,WAAA,CAAAQ,GAAA,EAACT,6BAAA,CAAAkB,KAAK;QAACd,QAAQ,EAAGA,QAAU;QAACY,IAAI,EAAC;MAAc,CAAE,CAAC;IAAA,CACrC;EAAC,CACR,CAAC;AAEZ","ignoreList":[]}
+{"version":3,"names":["_composite","require","_tooltip","_interopRequireDefault","_visuallyHidden","_utils","_styles","_jsxRuntime","Cell","id","value","props","jsx","default","text","ALIGNMENT_LABEL","children","jsxs","Composite","Item","render","role","VisuallyHidden","Point"],"sources":["@wordpress/components/src/alignment-matrix-control/cell.tsx"],"sourcesContent":["/**\n * Internal dependencies\n */\nimport { Composite } from '../composite';\nimport Tooltip from '../tooltip';\nimport { VisuallyHidden } from '../visually-hidden';\n\n/**\n * Internal dependencies\n */\nimport { ALIGNMENT_LABEL } from './utils';\nimport { Cell as CellView, Point } from './styles';\nimport type { AlignmentMatrixControlCellProps } from './types';\nimport type { WordPressComponentProps } from '../context';\n\nexport default function Cell( {\n\tid,\n\tvalue,\n\t...props\n}: WordPressComponentProps< AlignmentMatrixControlCellProps, 'span', false > ) {\n\treturn (\n\t\t<Tooltip text={ ALIGNMENT_LABEL[ value ] }>\n\t\t\t<Composite.Item\n\t\t\t\tid={ id }\n\t\t\t\trender={ <CellView { ...props } role=\"gridcell\" /> }\n\t\t\t>\n\t\t\t\t{ /* VoiceOver needs a text content to be rendered within grid cell,\n\t\t\totherwise it'll announce the content as \"blank\". So we use a visually\n\t\t\thidden element instead of aria-label. */ }\n\t\t\t\t<VisuallyHidden>{ value }</VisuallyHidden>\n\t\t\t\t<Point role=\"presentation\" />\n\t\t\t</Composite.Item>\n\t\t</Tooltip>\n\t);\n}\n"],"mappings":";;;;;;;AAGA,IAAAA,UAAA,GAAAC,OAAA;AACA,IAAAC,QAAA,GAAAC,sBAAA,CAAAF,OAAA;AACA,IAAAG,eAAA,GAAAH,OAAA;AAKA,IAAAI,MAAA,GAAAJ,OAAA;AACA,IAAAK,OAAA,GAAAL,OAAA;AAAmD,IAAAM,WAAA,GAAAN,OAAA;AAXnD;AACA;AACA;;AAKA;AACA;AACA;;AAMe,SAASO,IAAIA,CAAE;EAC7BC,EAAE;EACFC,KAAK;EACL,GAAGC;AACuE,CAAC,EAAG;EAC9E,oBACC,IAAAJ,WAAA,CAAAK,GAAA,EAACV,QAAA,CAAAW,OAAO;IAACC,IAAI,EAAGC,sBAAe,CAAEL,KAAK,CAAI;IAAAM,QAAA,eACzC,IAAAT,WAAA,CAAAU,IAAA,EAACjB,UAAA,CAAAkB,SAAS,CAACC,IAAI;MACdV,EAAE,EAAGA,EAAI;MACTW,MAAM,eAAG,IAAAb,WAAA,CAAAK,GAAA,EAACN,OAAA,CAAAE,IAAQ;QAAA,GAAMG,KAAK;QAAGU,IAAI,EAAC;MAAU,CAAE,CAAG;MAAAL,QAAA,gBAKpD,IAAAT,WAAA,CAAAK,GAAA,EAACR,eAAA,CAAAkB,cAAc;QAAAN,QAAA,EAAGN;MAAK,CAAkB,CAAC,eAC1C,IAAAH,WAAA,CAAAK,GAAA,EAACN,OAAA,CAAAiB,KAAK;QAACF,IAAI,EAAC;MAAc,CAAE,CAAC;IAAA,CACd;EAAC,CACT,CAAC;AAEZ","ignoreList":[]}