@wordpress/components 37.0.1-next.v.202607070741.0 → 38.0.0

package/src/content-editable-control/index.tsx

@@ -0,0 +1,110 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useMergeRefs } from '@wordpress/compose';
+import { forwardRef, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import BaseControl from '../base-control';
+import { useBaseControlProps } from '../base-control/hooks';
+import type { WordPressComponentProps } from '../context';
+import { VisuallyHidden } from '../visually-hidden';
+import type { ContentEditableControlProps } from './types';
+import styles from './style.module.scss';
+
+function UnforwardedContentEditableControl(
+	{
+		label,
+		id,
+		className,
+		help,
+		hideLabelFromVision,
+		disabled,
+		required,
+		placeholder,
+		...additionalProps
+	}: WordPressComponentProps< ContentEditableControlProps, 'div', false >,
+	forwardedRef: ForwardedRef< HTMLDivElement >
+) {
+	// The label is not passed through to `BaseControl`: it would render a
+	// `<label for>` pointing at the `contentEditable` `div`, which is not a
+	// labelable element, making the association invalid. The label is instead
+	// rendered here without `for` and wired up via `aria-labelledby`.
+	const { baseControlProps, controlProps } = useBaseControlProps( {
+		id,
+		className,
+		help,
+	} );
+
+	const labelId = `${ controlProps.id }__label`;
+	const editableRef = useRef< HTMLDivElement >( null );
+	const mergedRefs = useMergeRefs( [ editableRef, forwardedRef ] );
+
+	return (
+		<BaseControl { ...baseControlProps }>
+			{ hideLabelFromVision ? (
+				<VisuallyHidden id={ labelId }>{ label }</VisuallyHidden>
+			) : (
+				<BaseControl.VisualLabel
+					id={ labelId }
+					// Focus the field on label click, like `<label for>` would.
+					onClick={ () => editableRef.current?.focus() }
+				>
+					{ label }
+				</BaseControl.VisualLabel>
+			) }
+			<div
+				className={ styles.editable }
+				role="textbox"
+				aria-multiline
+				aria-labelledby={ labelId }
+				aria-placeholder={ placeholder || undefined }
+				aria-disabled={ disabled || undefined }
+				aria-required={ required || undefined }
+				ref={ mergedRefs }
+				// A disabled field is not `contentEditable`, which also
+				// removes it from the tab order.
+				contentEditable={ ! disabled }
+				suppressContentEditableWarning
+				{ ...additionalProps }
+				{ ...controlProps }
+			/>
+		</BaseControl>
+	);
+}
+
+/**
+ * A presentational `contentEditable` form control: a labeled editable element
+ * rendered with the chrome (`BaseControl` + label) shared by the other form
+ * controls in the package.
+ *
+ * Unlike the in-canvas `RichText` from `@wordpress/block-editor`, this control
+ * is intended for standalone form fields (DataForms, sidebar inputs, etc.).
+ * It is deliberately **presentational only** and has no `@wordpress/rich-text`
+ * dependency: the editable behavior (value, formatting, keyboard shortcuts)
+ * and any focus/selection tracking are owned by the consumer, which wires them
+ * through the forwarded ref and native event props (see the richtext DataForm
+ * control in `@wordpress/dataviews` for the canonical assembly).
+ *
+ * ```jsx
+ * // The rich-text "assembly" lives in the consumer.
+ * <ContentEditableControl
+ *     label="Caption"
+ *     ref={ mergedRef }
+ *     onFocus={ onEditableFocus }
+ *     onBlur={ onEditableBlur }
+ * />
+ * ```
+ */
+export const ContentEditableControl = forwardRef(
+	UnforwardedContentEditableControl
+);
+
+export default ContentEditableControl;

package/src/content-editable-control/stories/index.story.tsx

@@ -0,0 +1,32 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+/**
+ * Internal dependencies
+ */
+import ContentEditableControl from '..';
+
+const meta: Meta< typeof ContentEditableControl > = {
+	id: 'components-contenteditablecontrol',
+	title: 'Components/Selection & Input/Common/ContentEditableControl',
+	component: ContentEditableControl,
+	tags: [ 'status-private' ],
+	parameters: {
+		controls: { expanded: true },
+		docs: {
+			canvas: { sourceState: 'shown' },
+		},
+	},
+};
+export default meta;
+
+type Story = StoryObj< typeof ContentEditableControl >;
+
+export const Default: Story = {
+	args: {
+		label: 'Title',
+		placeholder: 'Add a title…',
+	},
+};

package/src/content-editable-control/style.module.scss

@@ -0,0 +1,34 @@
+@use "@wordpress/base-styles/mixins" as *;
+@use "@wordpress/base-styles/variables" as *;
+@use "../utils/theme-variables" as *;
+
+.editable {
+	width: 100%;
+	background: $components-color-background;
+	color: $components-color-foreground;
+	@include input-control;
+	border-color: $components-color-border;
+
+	// `::placeholder` only applies to native form fields, so draw the text
+	// from the `aria-placeholder` attribute while the element has no content.
+	&[aria-placeholder]:empty::before {
+		content: attr(aria-placeholder);
+		color: $components-color-dark-gray-placeholder;
+	}
+
+	min-height: $grid-unit-50;
+
+	// Subtract 1px to account for the border, which isn't included on the element
+	// on newer components like InputControl, SelectControl, etc.
+	// These values should be shared with the `controlPaddingX` in ./utils/config-values.js
+	padding: $grid-unit-15;
+
+	// Match the disabled treatment of native form controls (see the
+	// `&:disabled` rules in the textarea/input control styles).
+	&[aria-disabled="true"] {
+		background: $components-color-gray-100;
+		border-color: $components-color-gray-300;
+		color: $components-color-gray-700;
+		cursor: default;
+	}
+}

package/src/content-editable-control/test/index.tsx

@@ -0,0 +1,176 @@
+/**
+ * External dependencies
+ */
+import { render, screen, fireEvent } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import ContentEditableControl from '..';
+
+// The presentational shell is deliberately decoupled from `@wordpress/rich-text`:
+// the editable behavior and any focus/selection tracking are owned by the
+// consumer, wired through the forwarded ref and native event props. These
+// tests exercise only the chrome the shell owns -- the label and the
+// `contentEditable` element -- with no rich-text wiring at all.
+describe( 'ContentEditableControl', () => {
+	it( 'renders a labeled contenteditable textbox', () => {
+		render( <ContentEditableControl label="Description" /> );
+
+		const textbox = screen.getByRole( 'textbox' );
+		const label = screen.getByText( 'Description' );
+
+		expect( textbox ).toHaveAttribute( 'contenteditable', 'true' );
+		// A `<div contenteditable>` is not a labelable element, so the label
+		// must not use `for` (Chrome logs a console error for the invalid
+		// association). The name is wired through `aria-labelledby` instead.
+		expect( label ).not.toHaveAttribute( 'for' );
+		expect( textbox ).toHaveAttribute( 'aria-labelledby', label.id );
+		expect( textbox ).toHaveAccessibleName( 'Description' );
+	} );
+
+	it( 'focuses the textbox when the label is clicked', () => {
+		render( <ContentEditableControl label="Description" /> );
+
+		fireEvent.click( screen.getByText( 'Description' ) );
+
+		expect( screen.getByRole( 'textbox' ) ).toHaveFocus();
+	} );
+
+	it( 'visually hides the label when `hideLabelFromVision` is set', () => {
+		render( <ContentEditableControl label="Note" hideLabelFromVision /> );
+
+		const label = screen.getByText( 'Note' );
+		expect( label ).toHaveClass( 'components-visually-hidden' );
+	} );
+
+	it( 'is multiline by default and accepts an `aria-multiline` override', () => {
+		const { rerender } = render(
+			<ContentEditableControl label="Single line" />
+		);
+		expect( screen.getByRole( 'textbox' ) ).toHaveAttribute(
+			'aria-multiline',
+			'true'
+		);
+
+		rerender(
+			<ContentEditableControl
+				label="Single line"
+				aria-multiline={ false }
+			/>
+		);
+		expect( screen.getByRole( 'textbox' ) ).toHaveAttribute(
+			'aria-multiline',
+			'false'
+		);
+	} );
+
+	it( 'exposes `disabled` as a non-editable, aria-disabled textbox', () => {
+		render( <ContentEditableControl label="Note" disabled /> );
+
+		const textbox = screen.getByRole( 'textbox' );
+		expect( textbox ).toHaveAttribute( 'aria-disabled', 'true' );
+		expect( textbox ).toHaveAttribute( 'contenteditable', 'false' );
+	} );
+
+	it( 'exposes `required` via aria-required', () => {
+		render( <ContentEditableControl label="Note" required /> );
+
+		expect( screen.getByRole( 'textbox' ) ).toBeRequired();
+	} );
+
+	it( 'exposes `placeholder` via aria-placeholder', () => {
+		render(
+			<ContentEditableControl label="Note" placeholder="Add a note…" />
+		);
+
+		expect( screen.getByRole( 'textbox' ) ).toHaveAttribute(
+			'aria-placeholder',
+			'Add a note…'
+		);
+	} );
+
+	it( 'uses a consumer-supplied `id` for the textbox and label', () => {
+		render(
+			<ContentEditableControl
+				label="Custom id"
+				// eslint-disable-next-line no-restricted-syntax
+				id="my-custom-id"
+			/>
+		);
+
+		expect( screen.getByRole( 'textbox' ) ).toHaveAttribute(
+			'id',
+			'my-custom-id'
+		);
+		expect( screen.getByRole( 'textbox' ) ).toHaveAttribute(
+			'aria-labelledby',
+			'my-custom-id__label'
+		);
+		expect( screen.getByText( 'Custom id' ) ).toHaveAttribute(
+			'id',
+			'my-custom-id__label'
+		);
+	} );
+
+	it( 'applies a consumer-supplied className to the outermost wrapper', () => {
+		const { container } = render(
+			<ContentEditableControl
+				label="Styled"
+				className="my-custom-class"
+			/>
+		);
+
+		// The package convention is to put the consumer's `className` on the
+		// outermost wrapper (the `BaseControl` root), not the editable.
+		expect(
+			// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
+			container.querySelector( '.components-base-control' )
+		).toHaveClass( 'my-custom-class' );
+		expect( screen.getByRole( 'textbox' ) ).not.toHaveClass(
+			'my-custom-class'
+		);
+	} );
+
+	it( 'forwards additional native props to the textbox', () => {
+		render(
+			<ContentEditableControl
+				label="Note"
+				dir="rtl"
+				data-testid="my-textbox"
+			/>
+		);
+
+		const textbox = screen.getByRole( 'textbox' );
+		expect( textbox ).toHaveAttribute( 'dir', 'rtl' );
+		expect( textbox ).toHaveAttribute( 'data-testid', 'my-textbox' );
+	} );
+
+	it( 'forwards its ref to the contenteditable element', () => {
+		// The rich-text wiring (the `useRichText` ref, event-listener refs,
+		// an anchor ref, …) is injected through this forwarded ref.
+		const ref = jest.fn();
+		render( <ContentEditableControl label="Note" ref={ ref } /> );
+
+		expect( ref ).toHaveBeenCalledWith( screen.getByRole( 'textbox' ) );
+	} );
+
+	it( 'calls consumer-supplied focus and blur handlers', () => {
+		const onFocus = jest.fn();
+		const onBlur = jest.fn();
+		render(
+			<ContentEditableControl
+				label="Field"
+				onFocus={ onFocus }
+				onBlur={ onBlur }
+			/>
+		);
+		const textbox = screen.getByRole( 'textbox' );
+
+		fireEvent.focus( textbox );
+		expect( onFocus ).toHaveBeenCalledTimes( 1 );
+
+		fireEvent.blur( textbox );
+		expect( onBlur ).toHaveBeenCalledTimes( 1 );
+	} );
+} );

package/src/content-editable-control/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type ContentEditableControlProps = Pick<
+	BaseControlProps,
+	'className' | 'hideLabelFromVision' | 'help'
+> & {
+	/**
+	 * Label text for the control.
+	 */
+	label: string;
+	/**
+	 * Whether the field is non-editable. A disabled field is not
+	 * `contentEditable` (so it is neither focusable nor editable) and exposes
+	 * `aria-disabled` to assistive technology.
+	 *
+	 * @default false
+	 */
+	disabled?: boolean;
+	/**
+	 * Whether the field is required. Exposed to assistive technology via
+	 * `aria-required`.
+	 *
+	 * @default false
+	 */
+	required?: boolean;
+	/**
+	 * Placeholder text shown while the element has no content. Exposed to
+	 * assistive technology via `aria-placeholder` and drawn by the stylesheet
+	 * when the element is empty.
+	 */
+	placeholder?: string;
+};

package/src/context/test/__snapshots__/context-system-provider.js.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`props should render _override props 1`] = `
 <div>

package/src/context/wordpress-component.ts

@@ -34,8 +34,13 @@ export type WordPressComponent<
 	IsPolymorphic extends boolean,
 > = {
 	< TT extends React.ElementType >(
-		props: WordPressComponentProps< O, TT, IsPolymorphic > &
-			( IsPolymorphic extends true ? { as: TT } : {} )
+		props: WordPressComponentProps< O, TT, false > &
+			( IsPolymorphic extends true
+				? {
+						/** The HTML element or React component to render the component as. */
+						as: TT;
+				  }
+				: {} )
 	): React.ReactNode;
 	( props: WordPressComponentProps< O, T, IsPolymorphic > ): React.ReactNode;
 	displayName?: string;

package/src/custom-gradient-picker/test/index.tsx

@@ -1,15 +1,125 @@
 /**
  * External dependencies
  */
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
 /**
  * Internal dependencies
  */
 import CustomGradientPicker from '../';
 
+function ControlledCustomGradientPicker( {
+	initialValue = 'linear-gradient(90deg,rgb(0,0,0) 0%,rgb(255,255,255) 100%)',
+}: {
+	initialValue?: string;
+} ) {
+	const [ value, setValue ] = useState( initialValue );
+	return <CustomGradientPicker value={ value } onChange={ setValue } />;
+}
+
 describe( 'CustomGradientPicker', () => {
+	describe( 'new gradient stop color picker', () => {
+		it( 'preserves visual saturation when setting a new stop color through black', async () => {
+			const { container } = render( <ControlledCustomGradientPicker /> );
+
+			// Presentational gradient bar markup; no accessible roles.
+			// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
+			const markers = container.querySelector(
+				'.components-custom-gradient-picker__markers-container'
+			) as HTMLElement;
+			markers.getBoundingClientRect = () =>
+				( {
+					left: 0,
+					x: 0,
+					width: 200,
+					top: 0,
+					height: 20,
+					right: 200,
+					bottom: 20,
+					y: 0,
+					toJSON: () => ( {} ),
+				} ) as DOMRect;
+
+			// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
+			const bar = container.querySelector(
+				'.components-custom-gradient-picker__gradient-bar'
+			) as HTMLElement;
+			// Hover mid-bar so the insert-point control appears (away from 0%/100%).
+			fireEvent.mouseMove( bar, { clientX: 100 } );
+
+			// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
+			const insertButton = container.querySelector(
+				'.components-custom-gradient-picker__insert-point-dropdown'
+			) as HTMLElement;
+			expect( insertButton ).toBeTruthy();
+			fireEvent.click( insertButton );
+
+			const colorSlider = screen.getByRole( 'slider', { name: 'Color' } );
+			colorSlider.getBoundingClientRect = () =>
+				( {
+					left: 0,
+					top: 0,
+					width: 100,
+					height: 100,
+					right: 100,
+					bottom: 100,
+					x: 0,
+					y: 0,
+					toJSON: () => ( {} ),
+				} ) as DOMRect;
+
+			// Choose a saturated mid-brightness color — creates the new stop and
+			// exercises parent gradient updates while picking.
+			fireEvent.mouseDown( colorSlider, {
+				buttons: 1,
+				pageX: 80,
+				pageY: 20,
+				clientX: 80,
+				clientY: 20,
+			} );
+
+			// ColorPicker content is portaled; pointer has no accessible role.
+			// eslint-disable-next-line testing-library/no-node-access
+			const pointer = document.querySelector(
+				'.react-colorful__saturation-pointer'
+			) as HTMLElement;
+			expect( pointer ).toBeTruthy();
+			const leftBefore = pointer.style.left;
+			expect( parseFloat( leftBefore ) ).toBeGreaterThan( 50 );
+
+			// Keyboard to black — must not reset saturation via HSVA↔HSLA echo
+			// while the gradient parent keeps updating (#80110 / #80205).
+			colorSlider.focus();
+			for ( let i = 0; i < 20; i++ ) {
+				fireEvent.keyDown( colorSlider, {
+					key: 'ArrowDown',
+					keyCode: 40,
+					which: 40,
+				} );
+			}
+
+			expect( pointer ).toHaveStyle( {
+				top: '100%',
+				left: leftBefore,
+			} );
+
+			// Close the portaled popover so later tests are not affected by
+			// asynchronous Popover position updates.
+			fireEvent.click( insertButton );
+			await waitFor( () => {
+				expect(
+					screen.queryByRole( 'slider', { name: 'Color' } )
+				).not.toBeInTheDocument();
+			} );
+		} );
+	} );
+
 	describe( 'GradientTypePicker angle persistence', () => {
 		it( 'should restore the previous linear angle when switching from radial back to linear', async () => {
 			const user = userEvent.setup();

package/src/custom-select-control/index.tsx

@@ -62,7 +62,6 @@ function CustomSelectControl< T extends CustomSelectOption >(
 	const {
 		// Prevent passing legacy props to internal component.
 		__next40pxDefaultSize: _next40pxDefaultSize,
-		__shouldNotWarnDeprecated36pxSize: _shouldNotWarnDeprecated36pxSize,
 		describedBy,
 		options,
 		onChange,
@@ -177,7 +176,7 @@ function CustomSelectControl< T extends CustomSelectOption >(
 			<CustomSelect
 				aria-describedby={ descriptionId }
 				renderSelectedValue={ renderSelectedValue }
-				size={ size === '__unstable-large' ? 'default' : size }
+				size={ size }
 				store={ store }
 				className={ clsx(
 					// Keeping the classname for legacy reasons

package/src/custom-select-control/stories/index.story.tsx

@@ -34,7 +34,7 @@ const meta: Meta< typeof CustomSelectControl > = {
 		componentStatus: {
 			status: 'recommended',
 			whereUsed: 'global',
-			notes: 'Will be superseded by `SelectControl` in `@wordpress/ui`, but continue using for now.',
+			notes: 'Will be superseded by [`SelectControl`](?path=/docs/design-system-components-form-selectcontrol--docs) in `@wordpress/ui`, but continue using for now.',
 		},
 	},
 	decorators: [

package/src/custom-select-control/test/__snapshots__/index.tsx.snap

@@ -0,0 +1,6 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`Legacy size support treats __unstable-large the same as default 1`] = `
+Snapshot Diff:
+Compared values have no visual difference.
+`;

package/src/custom-select-control/test/index.tsx

@@ -694,6 +694,29 @@ describe.each( [
 	} );
 } );
 
+describe( 'Legacy size support', () => {
+	it( 'treats __unstable-large the same as default', async () => {
+		const options = [ { key: 'one', name: 'One' } ];
+
+		await render(
+			<UncontrolledCustomSelectControl label="Test" options={ options } />
+		);
+		await render(
+			<UncontrolledCustomSelectControl
+				label="Test"
+				options={ options }
+				// @ts-expect-error testing legacy runtime support for removed size type
+				size="__unstable-large"
+			/>
+		);
+
+		const comboboxes = screen.getAllByRole( 'combobox' );
+		const [ defaultCombobox, legacyCombobox ] = comboboxes;
+
+		expect( legacyCombobox ).toMatchStyleDiffSnapshot( defaultCombobox );
+	} );
+} );
+
 describe( 'Type checking', () => {
 	// eslint-disable-next-line jest/expect-expect
 	it( 'should infer the value type from available `options`, but not the `value` or `onChange` prop', () => {

package/src/custom-select-control/types.ts

@@ -89,7 +89,7 @@ export type CustomSelectProps< T extends CustomSelectOption > = {
 	 *
 	 * @default 'default'
 	 */
-	size?: 'default' | 'small' | '__unstable-large';
+	size?: 'default' | 'small';
 	/**
 	 * Can be used to externally control the value of the control.
 	 */
@@ -121,11 +121,4 @@ export type CustomSelectProps< T extends CustomSelectOption > = {
 	 * @ignore
 	 */
 	__next40pxDefaultSize?: boolean;
-	/**
-	 * Do not throw a warning for the deprecated 36px default size.
-	 * For internal components of other components that already throw the warning.
-	 *
-	 * @ignore
-	 */
-	__shouldNotWarnDeprecated36pxSize?: boolean;
 };

package/src/custom-select-control-v2/custom-select.tsx

@@ -131,11 +131,7 @@ function CustomSelect(
 			>
 				{ label }
 			</Ariakit.SelectLabel>
-			<InputBase
-				__next40pxDefaultSize
-				size={ size }
-				suffix={ <SelectControlChevronDown /> }
-			>
+			<InputBase size={ size } suffix={ <SelectControlChevronDown /> }>
 				<CustomSelectButton
 					{ ...restProps }
 					size={ size }

package/src/custom-select-control-v2/stories/index.story.tsx

@@ -34,7 +34,7 @@ const meta: Meta< typeof CustomSelectControlV2 > = {
 		componentStatus: {
 			status: 'not-recommended',
 			whereUsed: 'global',
-			notes: 'Will be superseded by `SelectControl` in `@wordpress/ui`. Continue using `CustomSelectControl` (v1) for now.',
+			notes: 'Will be superseded by [`SelectControl`](?path=/docs/design-system-components-form-selectcontrol--docs) in `@wordpress/ui`. Continue using `CustomSelectControl` (v1) for now.',
 		},
 	},
 	decorators: [

package/src/date-time/date-picker/styles.ts

@@ -38,7 +38,7 @@ export const NavigatorHeading = styled( Heading )`
 	grid-column: 2 / 7;
 
 	strong {
-		font-weight: ${ CONFIG.fontWeightHeading };
+		font-weight: ${ CONFIG.fontWeightEmphasis };
 	}
 `;
 

package/src/date-time/time-picker/index.tsx

@@ -136,7 +136,6 @@ export function TimePicker( {
 			className="components-datetime__time-field components-datetime__time-field-day" // Unused, for backwards compatibility.
 			label={ __( 'Day' ) }
 			hideLabelFromVision
-			__next40pxDefaultSize
 			value={ day }
 			step={ 1 }
 			min={ 1 }
@@ -177,7 +176,6 @@ export function TimePicker( {
 			className="components-datetime__time-field components-datetime__time-field-year" // Unused, for backwards compatibility.
 			label={ __( 'Year' ) }
 			hideLabelFromVision
-			__next40pxDefaultSize
 			value={ year }
 			step={ 1 }
 			min={ 1 }