@wordpress/components 39.0.0 → 40.1.1-next.v.202608281122.0

package/src/card/test/__snapshots__/index.tsx.snap

@@ -8,8 +8,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="css-1klm29z-Body css-3bn5lk-borderRadius css-15c2zrr-medium components-card__body components-card-body"
-+     class="css-drdujb-Scrollable css-1kynhwg-scrollableScrollbar css-flie1-scrollY components-scrollable css-1klm29z-Body css-3bn5lk-borderRadius css-15c2zrr-medium components-card__body components-card-body"
+-     class="css-1klm29z-Body css-15bowhl-borderRadius css-15c2zrr-medium components-card__body components-card-body"
++     class="style-scrollable style-scroll-y components-scrollable css-1focwqf-Body-ScrollableBody-getCardBodyStyles css-15bowhl-borderRadius css-15c2zrr-medium components-card__body components-card-body"
       data-wp-c16t="true"
       data-wp-component="CardBody"
     >
@@ -25,8 +25,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="css-1klm29z-Body css-3bn5lk-borderRadius css-15c2zrr-medium components-card__body components-card-body"
-+     class="css-1klm29z-Body css-3bn5lk-borderRadius css-15c2zrr-medium css-jr3vj2-shady components-card__body components-card-body"
+-     class="css-1klm29z-Body css-15bowhl-borderRadius css-15c2zrr-medium components-card__body components-card-body"
++     class="css-1klm29z-Body css-15bowhl-borderRadius css-15c2zrr-medium css-j3ztmn-shady components-card__body components-card-body"
       data-wp-c16t="true"
       data-wp-component="CardBody"
     >
@@ -42,8 +42,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="style-flex style-items-row style-expanded-row components-flex css-2thgtp-Footer-borderRadius-borderColor-medium-footerStyles components-card__footer components-card-footer"
-+     class="style-flex style-items-row style-expanded-row components-flex css-154en52-Footer-borderRadius-borderColor-medium-shady-footerStyles components-card__footer components-card-footer"
+-     class="style-flex style-items-row style-expanded-row components-flex css-5u84fb-Footer-borderRadius-borderColor-medium-footerStyles components-card__footer components-card-footer"
++     class="style-flex style-items-row style-expanded-row components-flex css-wdbpae-Footer-borderRadius-borderColor-medium-shady-footerStyles components-card__footer components-card-footer"
       data-wp-c16t="true"
       data-wp-component="CardFooter"
       style="--wp-components-flex-align: center; --wp-components-flex-direction: row; --wp-components-flex-wrap: nowrap; --wp-components-flex-gap: calc(4px * 2); --wp-components-flex-justify: space-between;"
@@ -58,7 +58,7 @@ Snapshot Diff:
 
   <div>
     <div
-      class="style-flex style-items-row style-expanded-row components-flex css-2thgtp-Footer-borderRadius-borderColor-medium-footerStyles components-card__footer components-card-footer"
+      class="style-flex style-items-row style-expanded-row components-flex css-5u84fb-Footer-borderRadius-borderColor-medium-footerStyles components-card__footer components-card-footer"
       data-wp-c16t="true"
       data-wp-component="CardFooter"
 -     style="--wp-components-flex-align: center; --wp-components-flex-direction: row; --wp-components-flex-wrap: nowrap; --wp-components-flex-gap: calc(4px * 2); --wp-components-flex-justify: space-between;"
@@ -77,8 +77,8 @@ Snapshot Diff:
 @@ -1,8 +1,8 @@
   <div>
     <div
--     class="style-flex style-items-row style-expanded-row components-flex css-ktwnuw-Header-borderRadius-borderColor-medium-headerStyles components-card__header components-card-header"
-+     class="style-flex style-items-row style-expanded-row components-flex css-wnar0y-Header-borderRadius-borderColor-medium-shady-headerStyles components-card__header components-card-header"
+-     class="style-flex style-items-row style-expanded-row components-flex css-yp7rat-Header-borderRadius-borderColor-medium-headerStyles components-card__header components-card-header"
++     class="style-flex style-items-row style-expanded-row components-flex css-6osy6f-Header-borderRadius-borderColor-medium-shady-headerStyles components-card__header components-card-header"
       data-wp-c16t="true"
       data-wp-component="CardHeader"
       style="--wp-components-flex-align: center; --wp-components-flex-direction: row; --wp-components-flex-wrap: nowrap; --wp-components-flex-gap: calc(4px * 2); --wp-components-flex-justify: space-between;"
@@ -97,8 +97,8 @@ Snapshot Diff:
         class="css-1ruapvy-Content"
       >
         <div
--         class="style-flex style-items-row style-expanded-row components-flex css-ktwnuw-Header-borderRadius-borderColor-medium-headerStyles components-card__header components-card-header"
-+         class="style-flex style-items-row style-expanded-row components-flex css-11nwurb-Header-borderRadius-borderColor-large-headerStyles components-card__header components-card-header"
+-         class="style-flex style-items-row style-expanded-row components-flex css-yp7rat-Header-borderRadius-borderColor-medium-headerStyles components-card__header components-card-header"
++         class="style-flex style-items-row style-expanded-row components-flex css-w6it5-Header-borderRadius-borderColor-large-headerStyles components-card__header components-card-header"
           data-wp-c16t="true"
           data-wp-component="CardHeader"
           style="--wp-components-flex-align: center; --wp-components-flex-direction: row; --wp-components-flex-wrap: nowrap; --wp-components-flex-gap: calc(4px * 2); --wp-components-flex-justify: space-between;"
@@ -106,8 +106,8 @@ Snapshot Diff:
           Header
         </div>
         <div
--         class="css-1klm29z-Body css-3bn5lk-borderRadius css-15c2zrr-medium components-card__body components-card-body"
-+         class="css-1klm29z-Body css-3bn5lk-borderRadius css-13uacf-large components-card__body components-card-body"
+-         class="css-1klm29z-Body css-15bowhl-borderRadius css-15c2zrr-medium components-card__body components-card-body"
++         class="css-1klm29z-Body css-15bowhl-borderRadius css-13uacf-large components-card__body components-card-body"
           data-wp-c16t="true"
           data-wp-component="CardBody"
         >
@@ -140,8 +140,8 @@ Snapshot Diff:
         class="css-1ruapvy-Content"
       >
         <div
--         class="style-flex style-items-row style-expanded-row components-flex css-vicxgd-Header-borderRadius-borderColor-large-borderless-headerStyles components-card__header components-card-header"
-+         class="style-flex style-items-row style-expanded-row components-flex css-15e9715-Header-borderRadius-borderColor-small-headerStyles components-card__header components-card-header"
+-         class="style-flex style-items-row style-expanded-row components-flex css-1vwbg0l-Header-borderRadius-borderColor-large-borderless-headerStyles components-card__header components-card-header"
++         class="style-flex style-items-row style-expanded-row components-flex css-cvlx89-Header-borderRadius-borderColor-small-headerStyles components-card__header components-card-header"
           data-wp-c16t="true"
           data-wp-component="CardHeader"
           style="--wp-components-flex-align: center; --wp-components-flex-direction: row; --wp-components-flex-wrap: nowrap; --wp-components-flex-gap: calc(4px * 2); --wp-components-flex-justify: space-between;"
@@ -149,16 +149,16 @@ Snapshot Diff:
           Header
         </div>
         <div
--         class="css-1klm29z-Body css-3bn5lk-borderRadius css-13uacf-large components-card__body components-card-body"
-+         class="css-1klm29z-Body css-3bn5lk-borderRadius css-15c2zrr-medium components-card__body components-card-body"
+-         class="css-1klm29z-Body css-15bowhl-borderRadius css-13uacf-large components-card__body components-card-body"
++         class="css-1klm29z-Body css-15bowhl-borderRadius css-15c2zrr-medium components-card__body components-card-body"
           data-wp-c16t="true"
           data-wp-component="CardBody"
         >
           Body
         </div>
         <div
--         class="style-flex style-items-row style-expanded-row components-flex css-1yqqqb5-Footer-borderRadius-borderColor-large-borderless-footerStyles components-card__footer components-card-footer"
-+         class="style-flex style-items-row style-expanded-row components-flex css-d48r1q-Footer-borderRadius-borderColor-xSmallCardPadding-footerStyles components-card__footer components-card-footer"
+-         class="style-flex style-items-row style-expanded-row components-flex css-1pvsads-Footer-borderRadius-borderColor-large-borderless-footerStyles components-card__footer components-card-footer"
++         class="style-flex style-items-row style-expanded-row components-flex css-155de53-Footer-borderRadius-borderColor-xSmallCardPadding-footerStyles components-card__footer components-card-footer"
           data-wp-c16t="true"
           data-wp-component="CardFooter"
           style="--wp-components-flex-align: center; --wp-components-flex-direction: row; --wp-components-flex-wrap: nowrap; --wp-components-flex-gap: calc(4px * 2); --wp-components-flex-justify: space-between;"
@@ -174,8 +174,8 @@ Snapshot Diff:
 @@ -1,31 +1,31 @@
   <div>
     <div
--     class="style-surface components-surface css-r8qwc0-Card-boxShadowless-rounded-cardStyles components-card"
-+     class="style-surface components-surface css-1ghyua5-Card-rounded-cardStyles components-card"
+-     class="style-surface components-surface css-2ndqpy-Card-boxShadowless-rounded-cardStyles components-card"
++     class="style-surface components-surface css-l49oe9-Card-rounded-cardStyles components-card"
       data-wp-c16t="true"
       data-wp-component="Card"
     >
@@ -183,8 +183,8 @@ Snapshot Diff:
         class="css-1ruapvy-Content"
       >
         <div
--         class="style-flex style-items-row style-expanded-row components-flex css-vicxgd-Header-borderRadius-borderColor-large-borderless-headerStyles components-card__header components-card-header"
-+         class="style-flex style-items-row style-expanded-row components-flex css-15e9715-Header-borderRadius-borderColor-small-headerStyles components-card__header components-card-header"
+-         class="style-flex style-items-row style-expanded-row components-flex css-1vwbg0l-Header-borderRadius-borderColor-large-borderless-headerStyles components-card__header components-card-header"
++         class="style-flex style-items-row style-expanded-row components-flex css-cvlx89-Header-borderRadius-borderColor-small-headerStyles components-card__header components-card-header"
           data-wp-c16t="true"
           data-wp-component="CardHeader"
           style="--wp-components-flex-align: center; --wp-components-flex-direction: row; --wp-components-flex-wrap: nowrap; --wp-components-flex-gap: calc(4px * 2); --wp-components-flex-justify: space-between;"
@@ -192,16 +192,16 @@ Snapshot Diff:
           Header
         </div>
         <div
--         class="css-1klm29z-Body css-3bn5lk-borderRadius css-13uacf-large components-card__body components-card-body"
-+         class="css-1klm29z-Body css-3bn5lk-borderRadius css-1a3bp49-small components-card__body components-card-body"
+-         class="css-1klm29z-Body css-15bowhl-borderRadius css-13uacf-large components-card__body components-card-body"
++         class="css-1klm29z-Body css-15bowhl-borderRadius css-1a3bp49-small components-card__body components-card-body"
           data-wp-c16t="true"
           data-wp-component="CardBody"
         >
           Body
         </div>
         <div
--         class="style-flex style-items-row style-expanded-row components-flex css-1yqqqb5-Footer-borderRadius-borderColor-large-borderless-footerStyles components-card__footer components-card-footer"
-+         class="style-flex style-items-row style-expanded-row components-flex css-1txkneh-Footer-borderRadius-borderColor-small-footerStyles components-card__footer components-card-footer"
+-         class="style-flex style-items-row style-expanded-row components-flex css-1pvsads-Footer-borderRadius-borderColor-large-borderless-footerStyles components-card__footer components-card-footer"
++         class="style-flex style-items-row style-expanded-row components-flex css-15rgdo1-Footer-borderRadius-borderColor-small-footerStyles components-card__footer components-card-footer"
           data-wp-c16t="true"
           data-wp-component="CardFooter"
           style="--wp-components-flex-align: center; --wp-components-flex-direction: row; --wp-components-flex-wrap: nowrap; --wp-components-flex-gap: calc(4px * 2); --wp-components-flex-justify: space-between;"

package/src/circular-option-picker/README.md

@@ -77,16 +77,20 @@ The child elements.
 
 - Required: No
 
-### `asButtons`: `boolean`
+### `presentation`: `'listbox' | 'toggle-buttons' | 'command-buttons'`
 
-Whether the control should present as a set of buttons, each with its own tab stop.
+Controls the swatches' interaction and accessibility semantics.
+
+-   `listbox` uses one tab stop for the picker. Arrow keys move between options. Options expose selection with `aria-selected`.
+-   `toggle-buttons` uses a tab stop for each swatch. Swatches expose selection with `aria-pressed`.
+-   `command-buttons` uses a tab stop for each swatch. Swatches do not expose selection. Use this presentation when each swatch runs a command, such as opening an editor.
 
 - Required: No
-- Default: `false`
+- Default: `listbox`
 
 ### `loop`: `boolean`
 
-Prevents keyboard interaction from wrapping around. Only used when `asButtons` is not true.
+Prevents arrow-key navigation from wrapping around. Only used with the `listbox` presentation.
 
 - Required: No
 - Default: `true`

package/src/circular-option-picker/circular-option-picker-option.tsx

@@ -79,7 +79,11 @@ export function Option( {
 	tooltipText,
 	...additionalProps
 }: OptionProps ) {
-	const { baseId, setActiveId } = useContext( CircularOptionPickerContext );
+	// Preserve the historical toggle-button fallback when this public
+	// subcomponent is rendered without a parent picker.
+	const { baseId, presentation = 'toggle-buttons' } = useContext(
+		CircularOptionPickerContext
+	);
 	const id = useInstanceId(
 		Option,
 		baseId || 'components-circular-option-picker__option'
@@ -91,20 +95,24 @@ export function Option( {
 		...additionalProps,
 	};
 
-	const isListbox = setActiveId !== undefined;
-	const optionControl = isListbox ? (
-		<OptionAsOption
-			{ ...commonProps }
-			label={ tooltipText }
-			isSelected={ isSelected }
-		/>
-	) : (
-		<OptionAsButton
-			{ ...commonProps }
-			label={ tooltipText }
-			isPressed={ isSelected }
-		/>
-	);
+	const optionControl =
+		presentation === 'listbox' ? (
+			<OptionAsOption
+				{ ...commonProps }
+				label={ tooltipText }
+				isSelected={ isSelected }
+			/>
+		) : (
+			<OptionAsButton
+				{ ...commonProps }
+				label={ tooltipText }
+				isPressed={
+					presentation === 'toggle-buttons'
+						? !! isSelected
+						: undefined
+				}
+			/>
+		);
 
 	return (
 		<div
@@ -114,7 +122,9 @@ export function Option( {
 			) }
 		>
 			{ optionControl }
-			{ isSelected && <Icon icon={ check } { ...selectedIconProps } /> }
+			{ presentation !== 'command-buttons' && isSelected && (
+				<Icon icon={ check } { ...selectedIconProps } />
+			) }
 		</div>
 	);
 }

package/src/circular-option-picker/circular-option-picker.tsx

@@ -15,6 +15,10 @@ import {
 	ButtonAction,
 	DropdownLinkAction,
 } from './circular-option-picker-actions';
+import {
+	resolveCircularOptionPickerPresentation,
+	warnIfCircularOptionPickerAsButtonsIsSet,
+} from './utils';
 
 /**
  *`CircularOptionPicker` is a component that displays a set of options as circular buttons.
@@ -83,6 +87,7 @@ function ListboxCircularOptionPicker(
 			baseId,
 			activeId,
 			setActiveId,
+			presentation: 'listbox' as const,
 		} ),
 		[ baseId, activeId, setActiveId ]
 	);
@@ -111,13 +116,21 @@ function ListboxCircularOptionPicker(
 function ButtonsCircularOptionPicker(
 	props: ButtonsCircularOptionPickerProps
 ) {
-	const { actions, options, children, baseId, ...additionalProps } = props;
+	const {
+		actions,
+		options,
+		children,
+		baseId,
+		presentation,
+		...additionalProps
+	} = props;
 
 	const contextValue = useMemo(
 		() => ( {
 			baseId,
+			presentation,
 		} ),
-		[ baseId ]
+		[ baseId, presentation ]
 	);
 
 	return (
@@ -134,12 +147,22 @@ function ButtonsCircularOptionPicker(
 function CircularOptionPicker( props: CircularOptionPickerProps ) {
 	const {
 		asButtons,
+		presentation,
+		loop,
 		actions: actionsProp,
 		options: optionsProp,
 		children,
 		className,
 		...additionalProps
 	} = props;
+	warnIfCircularOptionPickerAsButtonsIsSet(
+		'CircularOptionPicker',
+		asButtons
+	);
+	const resolvedPresentation = resolveCircularOptionPickerPresentation(
+		presentation,
+		asButtons
+	);
 
 	const baseId = useInstanceId(
 		CircularOptionPicker,
@@ -147,10 +170,6 @@ function CircularOptionPicker( props: CircularOptionPickerProps ) {
 		additionalProps.id
 	);
 
-	const OptionPickerImplementation = asButtons
-		? ButtonsCircularOptionPicker
-		: ListboxCircularOptionPicker;
-
 	const actions = actionsProp ? (
 		<div className="components-circular-option-picker__custom-clear-wrapper">
 			{ actionsProp }
@@ -163,16 +182,30 @@ function CircularOptionPicker( props: CircularOptionPickerProps ) {
 		</div>
 	);
 
+	const sharedProps = {
+		baseId,
+		className: clsx( 'components-circular-option-picker', className ),
+		actions,
+		options,
+		children,
+	};
+
+	if ( resolvedPresentation === 'listbox' ) {
+		return (
+			<ListboxCircularOptionPicker
+				{ ...additionalProps }
+				{ ...sharedProps }
+				loop={ loop }
+			/>
+		);
+	}
+
 	return (
-		<OptionPickerImplementation
+		<ButtonsCircularOptionPicker
 			{ ...additionalProps }
-			baseId={ baseId }
-			className={ clsx( 'components-circular-option-picker', className ) }
-			actions={ actions }
-			options={ options }
-		>
-			{ children }
-		</OptionPickerImplementation>
+			{ ...sharedProps }
+			presentation={ resolvedPresentation }
+		/>
 	);
 }
 

package/src/circular-option-picker/index.tsx

@@ -6,6 +6,10 @@ export {
 	ButtonAction,
 	DropdownLinkAction,
 } from './circular-option-picker-actions';
-export { getComputeCircularOptionPickerCommonProps } from './utils';
+export {
+	getComputeCircularOptionPickerCommonProps,
+	resolveCircularOptionPickerPresentation,
+	warnIfCircularOptionPickerAsButtonsIsSet,
+} from './utils';
 
 export default CircularOptionPicker;

package/src/circular-option-picker/stories/index.story.tsx

@@ -107,10 +107,10 @@ Default.args = {
 	options: <DefaultOptions />,
 };
 
-export const AsButtons = Template.bind( {} );
-AsButtons.args = {
+export const AsToggleButtons = Template.bind( {} );
+AsToggleButtons.args = {
 	...Default.args,
-	asButtons: true,
+	presentation: 'toggle-buttons',
 };
 
 export const WithLoopingDisabled = Template.bind( {} );

package/src/circular-option-picker/test/index.tsx

@@ -1,5 +1,6 @@
 import { render, screen } from '@testing-library/react';
 import { press } from '@ariakit/test';
+import { logged } from '@wordpress/deprecated';
 import CircularOptionPicker from '..';
 
 const SINGLE_OPTION = [ <CircularOptionPicker.Option key="option" /> ];
@@ -13,12 +14,35 @@ const DEFAULT_PROPS = {
 	'aria-label': 'Circular Option Picker',
 	options: SINGLE_OPTION,
 };
+const AS_BUTTONS_DEPRECATION =
+	'`asButtons` prop in wp.components.CircularOptionPicker is deprecated since version 7.2. Please use `presentation` instead. Note: `asButtons={ true }` maps to `presentation="toggle-buttons"`. Explicit `presentation` takes precedence.';
 
 function getOption( name: string ) {
 	return screen.getByRole( 'option', { name } );
 }
 
 describe( 'CircularOptionPicker', () => {
+	beforeEach( () => {
+		Object.keys( logged ).forEach( ( key ) => delete logged[ key ] );
+	} );
+
+	it( 'should preserve toggle-button semantics when an option is rendered without a picker', () => {
+		render(
+			<CircularOptionPicker.Option
+				isSelected
+				aria-label="Standalone option"
+			/>
+		);
+
+		expect(
+			screen.getByRole( 'button', {
+				name: 'Standalone option',
+				pressed: true,
+			} )
+		).toBeInTheDocument();
+		expect( screen.queryByRole( 'option' ) ).not.toBeInTheDocument();
+	} );
+
 	describe( 'when `asButtons` is not set', () => {
 		it( 'should render as a listbox', async () => {
 			render( <CircularOptionPicker { ...DEFAULT_PROPS } /> );
@@ -41,17 +65,142 @@ describe( 'CircularOptionPicker', () => {
 			expect( screen.getByRole( 'listbox' ) ).toBeInTheDocument();
 			expect( screen.getByRole( 'option' ) ).toBeInTheDocument();
 			expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
+			expect( console ).toHaveWarnedWith( AS_BUTTONS_DEPRECATION );
 		} );
 	} );
 
 	describe( 'when `asButtons` is true', () => {
-		it( 'should render as buttons', async () => {
-			render( <CircularOptionPicker { ...DEFAULT_PROPS } asButtons /> );
+		it( 'should render as toggle buttons with selected and unselected states', async () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					asButtons
+					options={ [
+						<CircularOptionPicker.Option
+							key="selected"
+							isSelected
+							aria-label="Selected"
+						/>,
+						<CircularOptionPicker.Option
+							key="unselected"
+							aria-label="Unselected"
+						/>,
+					] }
+				/>
+			);
 
 			expect( screen.queryByRole( 'listbox' ) ).not.toBeInTheDocument();
 			expect( screen.queryByRole( 'option' ) ).not.toBeInTheDocument();
 			expect( screen.getByRole( 'group' ) ).toBeInTheDocument();
-			expect( screen.getByRole( 'button' ) ).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Selected',
+					pressed: true,
+				} )
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Unselected',
+					pressed: false,
+				} )
+			).toBeInTheDocument();
+			expect( console ).toHaveWarnedWith( AS_BUTTONS_DEPRECATION );
+		} );
+	} );
+
+	describe( 'when `presentation` is set', () => {
+		it( 'should render a selected listbox option', () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					presentation="listbox"
+					options={ [
+						<CircularOptionPicker.Option
+							key="option"
+							isSelected
+							aria-label="Selected"
+						/>,
+					] }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'option', {
+					name: 'Selected',
+					selected: true,
+				} )
+			).toBeInTheDocument();
+		} );
+
+		it( 'should render toggle buttons with selected and unselected states', () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					presentation="toggle-buttons"
+					options={ [
+						<CircularOptionPicker.Option
+							key="selected"
+							isSelected
+							aria-label="Selected"
+						/>,
+						<CircularOptionPicker.Option
+							key="unselected"
+							aria-label="Unselected"
+						/>,
+					] }
+				/>
+			);
+
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Selected',
+					pressed: true,
+				} )
+			).toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', {
+					name: 'Unselected',
+					pressed: false,
+				} )
+			).toBeInTheDocument();
+		} );
+
+		it( 'should render command buttons without selection state or a selected check', () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					presentation="command-buttons"
+					options={ [
+						<CircularOptionPicker.Option
+							key="option"
+							isSelected
+							aria-label="Edit"
+						/>,
+					] }
+				/>
+			);
+
+			const button = screen.getByRole( 'button', { name: 'Edit' } );
+			expect( button ).not.toHaveAttribute( 'aria-pressed' );
+			expect( button ).not.toHaveAttribute( 'aria-selected' );
+			// The selected check is decorative and therefore has no semantic query.
+			// eslint-disable-next-line testing-library/no-node-access
+			expect( button.nextElementSibling ).toBeNull();
+		} );
+
+		it( 'should prefer an explicit presentation over asButtons', () => {
+			render(
+				<CircularOptionPicker
+					{ ...DEFAULT_PROPS }
+					asButtons
+					presentation="command-buttons"
+				/>
+			);
+
+			expect( screen.getByRole( 'button' ) ).not.toHaveAttribute(
+				'aria-pressed'
+			);
+			expect( console ).toHaveWarnedWith( AS_BUTTONS_DEPRECATION );
 		} );
 	} );
 

package/src/circular-option-picker/types.ts

@@ -4,7 +4,7 @@ import type { ButtonAsButtonProps } from '../button/types';
 import type { DropdownProps } from '../dropdown/types';
 import type { WordPressComponentProps } from '../context';
 
-type CommonCircularOptionPickerProps = {
+export type CircularOptionPickerProps = {
 	/**
 	 * An ID to apply to the component.
 	 */
@@ -29,6 +29,35 @@ type CommonCircularOptionPickerProps = {
 	 * The child elements.
 	 */
 	children?: ReactNode;
+	/**
+	 * How the swatches behave and are exposed to assistive technology.
+	 *
+	 * - `listbox` uses one tab stop and arrow-key navigation, and exposes
+	 *   selection with `aria-selected`.
+	 * - `toggle-buttons` gives each swatch a tab stop and exposes selection with
+	 *   `aria-pressed`.
+	 * - `command-buttons` gives each swatch a tab stop and exposes no selection
+	 *   state. Use it when swatches run commands such as opening an editor.
+	 *
+	 * @default 'listbox'
+	 */
+	presentation?: 'listbox' | 'toggle-buttons' | 'command-buttons';
+	/**
+	 * Whether the control should present as toggle buttons.
+	 *
+	 * @deprecated Use `presentation="toggle-buttons"` instead. An explicit
+	 * `presentation` takes precedence.
+	 * @default false
+	 * @ignore
+	 */
+	asButtons?: boolean;
+	/**
+	 * Prevents keyboard interaction from wrapping around.
+	 * Only used with the `listbox` presentation.
+	 *
+	 * @default true
+	 */
+	loop?: boolean;
 	/**
 	 * The ID reference list of one or more elements that label the wrapper
 	 * element.
@@ -45,40 +74,16 @@ type WithBaseId = {
 	baseId: string;
 };
 
-type FullListboxCircularOptionPickerProps = CommonCircularOptionPickerProps & {
-	/**
-	 * Whether the control should present as a set of buttons,
-	 * each with its own tab stop.
-	 */
-	asButtons?: false;
-	/**
-	 * Prevents keyboard interaction from wrapping around.
-	 * Only used when `asButtons` is not true.
-	 *
-	 * @default true
-	 */
-	loop?: boolean;
-};
-
 export type ListboxCircularOptionPickerProps = WithBaseId &
-	Omit< FullListboxCircularOptionPickerProps, 'asButtons' >;
-
-type FullButtonsCircularOptionPickerProps = CommonCircularOptionPickerProps & {
-	/**
-	 * Whether the control should present as a set of buttons,
-	 * each with its own tab stop.
-	 *
-	 * @default false
-	 */
-	asButtons: true;
-};
+	Omit< CircularOptionPickerProps, 'asButtons' | 'presentation' >;
 
 export type ButtonsCircularOptionPickerProps = WithBaseId &
-	Omit< FullButtonsCircularOptionPickerProps, 'asButtons' >;
-
-export type CircularOptionPickerProps =
-	| FullListboxCircularOptionPickerProps
-	| FullButtonsCircularOptionPickerProps;
+	Omit< CircularOptionPickerProps, 'asButtons' | 'presentation' | 'loop' > & {
+		presentation: Exclude<
+			NonNullable< CircularOptionPickerProps[ 'presentation' ] >,
+			'listbox'
+		>;
+	};
 
 export type DropdownLinkActionProps = {
 	buttonProps?: Omit<
@@ -116,4 +121,5 @@ export type CircularOptionPickerContextProps = {
 	baseId?: string;
 	activeId?: string | null | undefined;
 	setActiveId?: ( newId: string | null | undefined ) => void;
+	presentation?: CircularOptionPickerProps[ 'presentation' ];
 };