Composite: stabilize APIs (#63569)

* Use public export instead of private API * Remove Composite from private APIs * Refactor previously missed occurrences * CHANGELOG * Update CHANGELOG * Export Composite as public component * Fix ref type * Update CHANGELOG * Update Storybook * Remove experimental callout in README
WordPress · Sep 5, 2024 · 7cf62f7 · 7cf62f7
1 parent 05a12eb
commit 7cf62f7
Show file tree

Hide file tree

Showing 21 changed files with 60 additions and 143 deletions.
diff --git a/packages/block-directory/src/components/downloadable-block-list-item/index.js b/packages/block-directory/src/components/downloadable-block-list-item/index.js
@@ -6,7 +6,7 @@ import {
 	Button,
 	Spinner,
 	VisuallyHidden,
-	privateApis as componentsPrivateApis,
+	Composite,
 } from '@wordpress/components';
 import { createInterpolateElement } from '@wordpress/element';
 import { decodeEntities } from '@wordpress/html-entities';
@@ -20,9 +20,6 @@ import BlockRatings from '../block-ratings';
 import DownloadableBlockIcon from '../downloadable-block-icon';
 import DownloadableBlockNotice from '../downloadable-block-notice';
 import { store as blockDirectoryStore } from '../../store';
-import { unlock } from '../../lock-unlock';
-
-const { CompositeItemV2: CompositeItem } = unlock( componentsPrivateApis );
 
 // Return the appropriate block item label, given the block data and status.
 function getDownloadableBlockLabel(
@@ -93,7 +90,7 @@ function DownloadableBlockListItem( { item, onClick } ) {
 	}
 
 	return (
-		<CompositeItem
+		<Composite.Item
 			render={
 				<Button
 					// TODO: Switch to `true` (40px size) if possible
@@ -162,7 +159,7 @@ function DownloadableBlockListItem( { item, onClick } ) {
 					</>
 				) }
 			</span>
-		</CompositeItem>
+		</Composite.Item>
 	);
 }
 

diff --git a/packages/block-directory/src/components/downloadable-blocks-list/index.js b/packages/block-directory/src/components/downloadable-blocks-list/index.js
@@ -2,7 +2,7 @@
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
-import { privateApis as componentsPrivateApis } from '@wordpress/components';
+import { Composite } from '@wordpress/components';
 import { getBlockType } from '@wordpress/blocks';
 import { useDispatch } from '@wordpress/data';
 
@@ -11,9 +11,7 @@ import { useDispatch } from '@wordpress/data';
  */
 import DownloadableBlockListItem from '../downloadable-block-list-item';
 import { store as blockDirectoryStore } from '../../store';
-import { unlock } from '../../lock-unlock';
 
-const { CompositeV2: Composite } = unlock( componentsPrivateApis );
 const noop = () => {};
 
 function DownloadableBlocksList( { items, onHover = noop, onSelect } ) {

diff --git a/packages/block-editor/src/components/block-pattern-setup/index.js b/packages/block-editor/src/components/block-pattern-setup/index.js
@@ -3,10 +3,7 @@
  */
 import { useDispatch } from '@wordpress/data';
 import { cloneBlock } from '@wordpress/blocks';
-import {
-	VisuallyHidden,
-	privateApis as componentsPrivateApis,
-} from '@wordpress/components';
+import { Composite, VisuallyHidden } from '@wordpress/components';
 
 import { useState } from '@wordpress/element';
 import { useInstanceId } from '@wordpress/compose';
@@ -20,11 +17,6 @@ import BlockPreview from '../block-preview';
 import SetupToolbar from './setup-toolbar';
 import usePatternsSetup from './use-patterns-setup';
 import { VIEWMODES } from './constants';
-import { unlock } from '../../lock-unlock';
-
-const { CompositeV2: Composite, CompositeItemV2: CompositeItem } = unlock(
-	componentsPrivateApis
-);
 
 const SetupContent = ( {
 	viewMode,
@@ -88,7 +80,7 @@ function BlockPattern( { pattern, onSelect, showTitles } ) {
 	);
 	return (
 		<div className={ `${ baseClassName }__list-item` }>
-			<CompositeItem
+			<Composite.Item
 				render={
 					<div
 						aria-describedby={
@@ -116,7 +108,7 @@ function BlockPattern( { pattern, onSelect, showTitles } ) {
 						{ description }
 					</VisuallyHidden>
 				) }
-			</CompositeItem>
+			</Composite.Item>
 		</div>
 	);
 }

diff --git a/packages/block-editor/src/components/block-patterns-list/index.js b/packages/block-editor/src/components/block-patterns-list/index.js
@@ -9,9 +9,9 @@ import clsx from 'clsx';
 import { cloneBlock } from '@wordpress/blocks';
 import { useEffect, useState, forwardRef, useMemo } from '@wordpress/element';
 import {
+	Composite,
 	VisuallyHidden,
 	Tooltip,
-	privateApis as componentsPrivateApis,
 	__experimentalHStack as HStack,
 } from '@wordpress/components';
 import { useInstanceId } from '@wordpress/compose';
@@ -21,16 +21,11 @@ import { Icon, symbol } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
-import { unlock } from '../../lock-unlock';
 import BlockPreview from '../block-preview';
 import InserterDraggableBlocks from '../inserter-draggable-blocks';
 import BlockPatternsPaging from '../block-patterns-paging';
 import { INSERTER_PATTERN_TYPES } from '../inserter/block-patterns-tab/utils';
 
-const { CompositeV2: Composite, CompositeItemV2: CompositeItem } = unlock(
-	componentsPrivateApis
-);
-
 const WithToolTip = ( { showTooltip, title, children } ) => {
 	if ( showTooltip ) {
 		return <Tooltip text={ title }>{ children }</Tooltip>;
@@ -105,7 +100,7 @@ function BlockPattern( {
 						}
 						title={ pattern.title }
 					>
-						<CompositeItem
+						<Composite.Item
 							render={
 								<div
 									role="option"
@@ -174,7 +169,7 @@ function BlockPattern( {
 									{ pattern.description }
 								</VisuallyHidden>
 							) }
-						</CompositeItem>
+						</Composite.Item>
 					</WithToolTip>
 				</div>
 			) }

diff --git a/packages/block-editor/src/components/block-switcher/pattern-transformations-menu.js b/packages/block-editor/src/components/block-switcher/pattern-transformations-menu.js
@@ -7,23 +7,18 @@ import { useInstanceId, useViewportMatch } from '@wordpress/compose';
 import { chevronRight } from '@wordpress/icons';
 
 import {
+	Composite,
 	MenuGroup,
 	MenuItem,
 	Popover,
 	VisuallyHidden,
-	privateApis as componentsPrivateApis,
 } from '@wordpress/components';
 
 /**
  * Internal dependencies
  */
 import BlockPreview from '../block-preview';
 import useTransformedPatterns from './use-transformed-patterns';
-import { unlock } from '../../lock-unlock';
-
-const { CompositeV2: Composite, CompositeItemV2: CompositeItem } = unlock(
-	componentsPrivateApis
-);
 
 function PatternTransformationsMenu( {
 	blocks,
@@ -107,7 +102,7 @@ function BlockPattern( { pattern, onSelect } ) {
 	);
 	return (
 		<div className={ `${ baseClassName }-list__list-item` }>
-			<CompositeItem
+			<Composite.Item
 				render={
 					<div
 						role="option"
@@ -127,7 +122,7 @@ function BlockPattern( { pattern, onSelect } ) {
 				<div className={ `${ baseClassName }-list__item-title` }>
 					{ pattern.title }
 				</div>
-			</CompositeItem>
+			</Composite.Item>
 			{ !! pattern.description && (
 				<VisuallyHidden id={ descriptionId }>
 					{ pattern.description }

diff --git a/packages/block-editor/src/components/global-styles/shadow-panel-components.js b/packages/block-editor/src/components/global-styles/shadow-panel-components.js
@@ -10,7 +10,7 @@ import {
 	Button,
 	FlexItem,
 	Dropdown,
-	privateApis as componentsPrivateApis,
+	Composite,
 } from '@wordpress/components';
 import { useMemo } from '@wordpress/element';
 import { shadow as shadowIcon, Icon, check } from '@wordpress/icons';
@@ -20,21 +20,13 @@ import { shadow as shadowIcon, Icon, check } from '@wordpress/icons';
  */
 import clsx from 'clsx';
 
-/**
- * Internal dependencies
- */
-import { unlock } from '../../lock-unlock';
-
 /**
  * Shared reference to an empty array for cases where it is important to avoid
  * returning a new array reference on every invocation.
  *
  * @type {Array}
  */
 const EMPTY_ARRAY = [];
-const { CompositeItemV2: CompositeItem, CompositeV2: Composite } = unlock(
-	componentsPrivateApis
-);
 
 export function ShadowPopoverContainer( { shadow, onShadowChange, settings } ) {
 	const shadows = useShadowPresets( settings );
@@ -88,7 +80,7 @@ export function ShadowPresets( { presets, activeShadow, onSelect } ) {
 
 export function ShadowIndicator( { type, label, isActive, onSelect, shadow } ) {
 	return (
-		<CompositeItem
+		<Composite.Item
 			role="option"
 			aria-label={ label }
 			aria-selected={ isActive }

diff --git a/packages/block-editor/src/components/inserter-listbox/index.js b/packages/block-editor/src/components/inserter-listbox/index.js
@@ -1,19 +1,16 @@
 /**
  * WordPress dependencies
  */
-import { privateApis as componentsPrivateApis } from '@wordpress/components';
+import { Composite } from '@wordpress/components';
 
 /**
  * Internal dependencies
  */
-import { unlock } from '../../lock-unlock';
 
 export { default as InserterListboxGroup } from './group';
 export { default as InserterListboxRow } from './row';
 export { default as InserterListboxItem } from './item';
 
-const { CompositeV2: Composite } = unlock( componentsPrivateApis );
-
 function InserterListbox( { children } ) {
 	return (
 		<Composite focusShift focusWrap="horizontal" render={ <></> }>

diff --git a/packages/block-editor/src/components/inserter-listbox/item.js b/packages/block-editor/src/components/inserter-listbox/item.js
@@ -1,28 +1,18 @@
 /**
  * WordPress dependencies
  */
-import {
-	Button,
-	privateApis as componentsPrivateApis,
-} from '@wordpress/components';
+import { Button, Composite } from '@wordpress/components';
 import { forwardRef } from '@wordpress/element';
 
-/**
- * Internal dependencies
- */
-import { unlock } from '../../lock-unlock';
-
-const { CompositeItemV2: CompositeItem } = unlock( componentsPrivateApis );
-
 function InserterListboxItem(
 	{ isFirst, as: Component, children, ...props },
 	ref
 ) {
 	return (
-		<CompositeItem
+		<Composite.Item
 			ref={ ref }
 			role="option"
-			// Use the CompositeItem `accessibleWhenDisabled` prop
+			// Use the Composite.Item `accessibleWhenDisabled` prop
 			// over Button's `isFocusable`. The latter was shown to
 			// cause an issue with tab order in the inserter list.
 			accessibleWhenDisabled

diff --git a/packages/block-editor/src/components/inserter-listbox/row.js b/packages/block-editor/src/components/inserter-listbox/row.js
@@ -2,17 +2,10 @@
  * WordPress dependencies
  */
 import { forwardRef } from '@wordpress/element';
-import { privateApis as componentsPrivateApis } from '@wordpress/components';
-
-/**
- * Internal dependencies
- */
-import { unlock } from '../../lock-unlock';
-
-const { CompositeGroupV2: CompositeGroup } = unlock( componentsPrivateApis );
+import { Composite } from '@wordpress/components';
 
 function InserterListboxRow( props, ref ) {
-	return <CompositeGroup role="presentation" ref={ ref } { ...props } />;
+	return <Composite.Group role="presentation" ref={ ref } { ...props } />;
 }
 
 export default forwardRef( InserterListboxRow );
diff --git a/packages/block-editor/src/components/inserter/media-tab/media-list.js b/packages/block-editor/src/components/inserter/media-tab/media-list.js
@@ -1,16 +1,13 @@
 /**
  * WordPress dependencies
  */
-import { privateApis as componentsPrivateApis } from '@wordpress/components';
+import { Composite } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
  */
 import { MediaPreview } from './media-preview';
-import { unlock } from '../../../lock-unlock';
-
-const { CompositeV2: Composite } = unlock( componentsPrivateApis );
 
 function MediaList( {
 	mediaList,

diff --git a/packages/block-editor/src/components/inserter/media-tab/media-preview.js b/packages/block-editor/src/components/inserter/media-tab/media-preview.js
@@ -16,7 +16,7 @@ import {
 	Flex,
 	FlexItem,
 	Button,
-	privateApis as componentsPrivateApis,
+	Composite,
 	__experimentalVStack as VStack,
 } from '@wordpress/components';
 import { __, sprintf } from '@wordpress/i18n';
@@ -33,7 +33,6 @@ import { isBlobURL } from '@wordpress/blob';
 import InserterDraggableBlocks from '../../inserter-draggable-blocks';
 import { getBlockAndPreviewFromMedia } from './utils';
 import { store as blockEditorStore } from '../../../store';
-import { unlock } from '../../../lock-unlock';
 
 const ALLOWED_MEDIA_TYPES = [ 'image' ];
 const MAXIMUM_TITLE_LENGTH = 25;
@@ -43,8 +42,6 @@ const MEDIA_OPTIONS_POPOVER_PROPS = {
 		'block-editor-inserter__media-list__item-preview-options__popover',
 };
 
-const { CompositeItemV2: CompositeItem } = unlock( componentsPrivateApis );
-
 function MediaPreviewOptions( { category, media } ) {
 	if ( ! category.getReportUrl ) {
 		return null;
@@ -249,7 +246,7 @@ export function MediaPreview( { media, onClick, category } ) {
 							onMouseLeave={ onMouseLeave }
 						>
 							<Tooltip text={ truncatedTitle || title }>
-								<CompositeItem
+								<Composite.Item
 									render={
 										<div
 											aria-label={ title }
@@ -267,7 +264,7 @@ export function MediaPreview( { media, onClick, category } ) {
 											</div>
 										) }
 									</div>
-								</CompositeItem>
+								</Composite.Item>
 							</Tooltip>
 							{ ! isInserting && (
 								<MediaPreviewOptions

diff --git a/packages/components/CHANGELOG.md b/packages/components/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### New Features
+
+-   `Composite`: add stable version of the component ([#63569](https://github.com/WordPress/gutenberg/pull/63569)).
+
+### Internal
+
+-   `Composite`: Remove from private APIs ([#63569](https://github.com/WordPress/gutenberg/pull/63569)).
+
 ## 28.7.0 (2024-09-05)
 
 ### Deprecations

diff --git a/packages/components/src/composite/README.md b/packages/components/src/composite/README.md
@@ -1,9 +1,5 @@
 # `Composite`
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 `Composite` provides a single tab stop on the page and allows navigation through the focusable descendants with arrow keys. This abstract component is based on the [WAI-ARIA Composite Role⁠](https://w3c.github.io/aria/#composite).
 
 ## Usage

diff --git a/packages/components/src/composite/legacy/stories/index.story.tsx b/packages/components/src/composite/legacy/stories/index.story.tsx
@@ -15,7 +15,8 @@ import {
 import { UseCompositeStatePlaceholder, transform } from './utils';
 
 const meta: Meta< typeof UseCompositeStatePlaceholder > = {
-	title: 'Components/Composite',
+	title: 'Components (Deprecated)/Composite (Unstable)',
+	id: 'components-composite-unstable',
 	component: UseCompositeStatePlaceholder,
 	subcomponents: {
 		Composite,