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

package/src/button/style.scss

@@ -12,6 +12,11 @@
  */
 
 .components-button {
+	// Defend against a conflicting focus ring from WordPress common.css on `a:focus`.
+	&:focus:is(a) {
+		box-shadow: none;
+	}
+
 	&:focus:not(:active) {
 		@include mixins.outset-ring__focus();
 	}
@@ -20,9 +25,8 @@
 	text-decoration: none;
 	font-family: inherit;
 	font-size: $default-font-size;
-	font-weight: $font-weight-medium;
+	font-weight: var(--wpds-typography-font-weight-emphasis);
 	margin: 0;
-	border: 0;
 	cursor: var(--wpds-cursor-control);
 	appearance: none;
 	background: none;
@@ -32,6 +36,9 @@
 	padding: 4px 12px; // Allows 32px min-height.
 	border-radius: $radius-small;
 	color: $components-color-foreground;
+	// Every variant reserves a 1px border (transparent by default) so the box
+	// size stays identical whether or not a variant paints a visible border.
+	border: $border-width solid transparent;
 
 	&.is-next-40px-default-size {
 		height: $button-size-next-default-40px;
@@ -88,10 +95,6 @@
 			);
 			/* stylelint-enable */
 		}
-
-		@media (forced-colors: active) {
-			outline: 1px solid ButtonBorder;
-		}
 	}
 
 	/**
@@ -100,10 +103,6 @@
 
 	&.is-secondary,
 	&.is-tertiary {
-		&:active:not(:disabled) {
-			box-shadow: none;
-		}
-
 		&:disabled,
 		&[aria-disabled="true"],
 		&[aria-disabled="true"]:hover {
@@ -111,10 +110,6 @@
 			background: transparent;
 			transform: none;
 		}
-
-		@media (forced-colors: active) {
-			outline: 1px solid ButtonBorder;
-		}
 	}
 
 	/**
@@ -123,31 +118,33 @@
 
 	&.is-secondary {
 		@media not ( prefers-reduced-motion ) {
-			transition: box-shadow 0.1s linear;
+			transition: border-color 0.1s linear;
 		}
 
-		box-shadow:
-			inset 0 0 0 $border-width $components-color-accent,
-			0 0 0 currentColor;
+		border-color: $components-color-accent;
 		white-space: nowrap;
 		color: $components-color-accent;
 		background: transparent;
 
+		&:active:not(:disabled) {
+			// Hide the border while pressed, keeping its width to avoid a size shift.
+			border-color: transparent;
+		}
+
 		&:hover:not(:disabled, [aria-disabled="true"], .is-pressed) {
-			box-shadow: inset 0 0 0 $border-width $components-color-accent-darker-20;
+			border-color: $components-color-accent-darker-20;
 			color: $components-color-accent-darker-20;
 			background: color-mix(in srgb, $components-color-accent 4%, transparent);
 		}
 
+		&:focus:not(:active) {
+			border-color: $components-color-accent;
+		}
+
 		&:disabled:not(:focus),
 		&[aria-disabled="true"]:not(:focus),
 		&[aria-disabled="true"]:hover:not(:focus) {
-			box-shadow: inset 0 0 0 $border-width var(--wpds-color-stroke-interactive-neutral-disabled);
-		}
-
-		@media (forced-colors: active) {
-			// Inset box-shadow borders are not reliable in forced-colors mode.
-			box-shadow: none;
+			border-color: var(--wpds-color-stroke-interactive-neutral-disabled);
 		}
 	}
 
@@ -220,13 +217,12 @@
 	&.is-link {
 		margin: 0;
 		padding: 0;
-		box-shadow: none;
 		border: 0;
 		border-radius: 0;
 		background: none;
 		outline: none;
 		text-align: left;
-		font-weight: $font-weight-regular;
+		font-weight: var(--wpds-typography-font-weight-default);
 		color: $components-color-accent;
 		text-decoration: underline;
 		text-underline-offset: 0.2em;
@@ -331,6 +327,15 @@
 				padding-left: $grid-unit-15;
 			}
 		}
+
+		// Offset the reserved 1px border so it doesn't widen the square
+		// icon button.
+		&:not(.has-text) {
+			svg,
+			.dashicon {
+				margin-inline: -$border-width;
+			}
+		}
 	}
 
 	// Toggled style.

package/src/button-group/style.scss

@@ -8,7 +8,7 @@
 		border-radius: 0;
 		display: inline-flex;
 		color: $gray-900;
-		box-shadow: inset 0 0 0 $border-width $gray-900;
+		border-color: $gray-900;
 
 		& + .components-button {
 			margin-left: -1px;
@@ -29,10 +29,5 @@
 			position: relative;
 			z-index: 1;
 		}
-
-		// The active button should look pressed.
-		&.is-primary {
-			box-shadow: inset 0 0 0 $border-width $gray-900;
-		}
 	}
 }

package/src/calendar/style.scss

@@ -21,7 +21,7 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	color: $components-color-foreground;
 	background-color: $components-color-background;
 	font-size: $font-size-medium;
-	font-weight: $font-weight-regular;
+	font-weight: var(--wpds-typography-font-weight-default);
 	z-index: 0; // Create a stacking context and render on top of the background.
 
 	*,

package/src/card/stories/index.story.tsx

@@ -32,7 +32,7 @@ const meta: Meta< typeof Card > = {
 		componentStatus: {
 			status: 'not-recommended',
 			whereUsed: 'global',
-			notes: 'Use `Card` or `CollapsibleCard` from `@wordpress/ui` instead.',
+			notes: 'Use [`Card`](?path=/docs/design-system-components-card--docs) or [`CollapsibleCard`](?path=/docs/design-system-components-collapsiblecard--docs) from `@wordpress/ui` instead.',
 		},
 	},
 };

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

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Card Card component CardBody should allow scrolling content with the scrollable prop is true 1`] = `
 Snapshot Diff:

package/src/checkbox-control/stories/index.story.tsx

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

package/src/checkbox-control/test/__snapshots__/index.tsx.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`CheckboxControl Basic rendering should render the indeterminate icon when in the indeterminate state 1`] = `
 Snapshot Diff:

package/src/color-indicator/test/__snapshots__/index.tsx.snap

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

package/src/color-palette/styles.ts

@@ -12,7 +12,7 @@ import { CONFIG } from '../utils';
 export const ColorHeading = styled( Heading )`
 	text-transform: uppercase;
 	line-height: 24px;
-	font-weight: ${ CONFIG.fontWeightMedium };
+	font-weight: ${ CONFIG.fontWeightEmphasis };
 	&&& {
 		font-size: 11px;
 		margin-bottom: 0;

package/src/color-picker/component.tsx

@@ -98,42 +98,40 @@ const UnconnectedColorPicker = (
 	// distinguish our own updates from external prop changes.
 	const lastProducedHexRef = useRef( safeColordColor.toHex() );
 
+	// While the user is dragging the visual picker, ignore color-prop sync
+	// so delayed/stale controlled echoes cannot overwrite internalHSLA mid-drag.
+	const isPickerInteractingRef = useRef( false );
+
 	// Sync internalHSLA when the color prop changes externally (e.g.
 	// parent passes a new color that wasn't produced by our onChange).
 	useEffect( () => {
-		const incomingHex = safeColordColor.toHex();
+		if ( isPickerInteractingRef.current ) {
+			return;
+		}
 
-		// If this hex matches what we last produced, it's our own
-		// update arriving back — skip the sync to avoid overwriting
-		// internalHSLA with lossy round-tripped values.
-		if ( incomingHex === lastProducedHexRef.current ) {
+		// Compare by color equality, not hex string — rgb()/rgba()
+		// round-trips can differ in string form for the same color.
+		if ( safeColordColor.isEqual( lastProducedHexRef.current ) ) {
 			return;
 		}
 
 		// Genuinely external change — sync internalHSLA.
-		lastProducedHexRef.current = incomingHex;
+		lastProducedHexRef.current = safeColordColor.toHex();
 		const externalHSLA = safeColordColor.toHsl();
 		setInternalHSLA( ( prev ) => mergeHSLA( externalHSLA, prev ) );
 	}, [ safeColordColor ] );
 
-	// Handler for HSL-aware components (Picker, HSL inputs) that
-	// provide raw HSLA values without information loss.
-	// Uses direct setColor (not debounced) to prevent race conditions
-	// where a stale debounced hex would overwrite newer internalHSLA.
-	// This is safe performance-wise because react-colorful internally
-	// throttles its onChange callbacks using requestAnimationFrame.
-
+	// Handler for HSL inputs (and the HSVA picker after it converts to HSLA).
+	// Apply the user's HSLA, then notify the parent only when the color
+	// actually changes. setColor must not run inside setInternalHSLA
+	// (state updaters must be pure). Uses direct setColor (not debounced)
+	// to avoid races with hex/RGB's debouncedSetColor.
 	const handleHSLAChange = useCallback(
 		( nextHSLA: HslaColor ) => {
-			// No mergeHSLA here — this handler receives the user's explicit
-			// choice from the picker or HSL inputs, with no lossy conversion.
 			setInternalHSLA( nextHSLA );
 			const previousHex = lastProducedHexRef.current;
 			const nextHex = colord( nextHSLA ).toHex();
-			// Only notify parent when the hex actually changes. This
-			// avoids firing onChange for H/S changes on achromatic
-			// colors (e.g. adjusting hue on pure white).
-			if ( nextHex !== previousHex ) {
+			if ( ! colord( nextHex ).isEqual( previousHex ) ) {
 				lastProducedHexRef.current = nextHex;
 				setColor( nextHex );
 			}
@@ -213,6 +211,12 @@ const UnconnectedColorPicker = (
 				onChange={ handleHSLAChange }
 				hsla={ internalHSLA }
 				enableAlpha={ enableAlpha }
+				onInteractionStart={ () => {
+					isPickerInteractingRef.current = true;
+				} }
+				onInteractionEnd={ () => {
+					isPickerInteractingRef.current = false;
+				} }
 			/>
 			<AuxiliaryColorArtefactWrapper>
 				<AuxiliaryColorArtefactHStackHeader justify="space-between">

package/src/color-picker/hex-input.tsx

@@ -58,7 +58,6 @@ export const HexInput = ( { color, onChange, enableAlpha }: HexInputProps ) => {
 			maxLength={ enableAlpha ? 9 : 7 }
 			label={ __( 'Hex color' ) }
 			hideLabelFromVision
-			size="__unstable-large"
 			__unstableStateReducer={ stateReducer }
 			__unstableInputWidth="9em"
 		/>

package/src/color-picker/input-with-slider.tsx

@@ -31,7 +31,6 @@ export const InputWithSlider = ( {
 	return (
 		<HStack spacing={ 4 }>
 			<NumberControlWrapper
-				__next40pxDefaultSize
 				min={ min }
 				max={ max }
 				label={ label }

package/src/color-picker/picker.tsx

@@ -1,42 +1,165 @@
 /**
  * External dependencies
  */
-import { HslColorPicker, HslaColorPicker } from 'react-colorful';
+import type { PointerEvent } from 'react';
+import { useEffect, useRef, useState } from '@wordpress/element';
+import { HsvColorPicker, HsvaColorPicker } from 'react-colorful';
+import { colord } from 'colord';
+import type { HslaColor, HsvaColor } from 'react-colorful';
 
 /**
  * Internal dependencies
  */
 import type { PickerProps } from './types';
 
-// Pointer capture fortifies drag gestures so that they continue to work
-// while dragging outside the component over objects like iframes. If a
-// newer version of react-colorful begins to employ pointer capture this
-// will be redundant and should be removed.
-const pointerCaptureProps = {
-	onPointerDown( { currentTarget, pointerId }: React.PointerEvent ) {
-		currentTarget.setPointerCapture( pointerId );
-	},
-	onPointerUp( { currentTarget, pointerId }: React.PointerEvent ) {
-		currentTarget.releasePointerCapture( pointerId );
-	},
-};
+function toHsva( hsla: PickerProps[ 'hsla' ] ): HsvaColor {
+	return {
+		...colord( hsla ).toHsv(),
+		// HSL and HSV share the hue angle. Color conversion collapses achromatic
+		// hue to 0, but HSLA retains the user's latent hue.
+		h: hsla.h,
+		a: hsla.a,
+	};
+}
+
+function isSameHsla( a: HslaColor, b: HslaColor ): boolean {
+	return a.h === b.h && a.s === b.s && a.l === b.l && a.a === b.a;
+}
+
+/**
+ * Convert parent HSLA into HSVA for prop sync.
+ *
+ * At black, RGB round-trips collapse saturation to 0. Preserve the native
+ * HSVA saturation coordinate unless the HSL saturation channel itself
+ * changed (sibling hue/alpha edits must not snap the pointer).
+ *
+ * At white, only `v: 100, s: 0` is visually white — preserving a prior
+ * chromatic saturation would leave the pointer at the top-right and make
+ * the first keyboard step jump from white to a saturated color.
+ */
+function toHsvaFromHsla(
+	hsla: HslaColor,
+	prevHsva: HsvaColor,
+	prevHsla: HslaColor | null
+): HsvaColor {
+	const converted = toHsva( hsla );
+
+	// White and chromatic colors use the converted value as-is.
+	if ( hsla.l !== 0 ) {
+		return converted;
+	}
+
+	const saturationChanged = prevHsla !== null && prevHsla.s !== hsla.s;
+
+	return {
+		h: hsla.h,
+		s: saturationChanged ? hsla.s : prevHsva.s,
+		v: 0,
+		a: hsla.a,
+	};
+}
+
+/**
+ * Visual color surface.
+ *
+ * Uses HSVA (react-colorful's native model) and keeps that value in local
+ * state so HSLA↔hex round-trips cannot move the pointer
+ * Parent ColorPicker still speaks HSLA for
+ * inputs and controlled value sync; conversion happens only at the boundary.
+ *
+ * Prop sync from parent HSLA is suppressed for:
+ * - pointer/touch drags (interaction flag), and
+ * - any picker-originated update including keyboard (HSLA origin token).
+ *
+ * Achromatic HSL sibling edits (hue/alpha while at black) preserve native
+ * HSVA saturation unless saturation itself changed. White always syncs to
+ * the converted `s: 0` visual coordinate.
+ */
+export const Picker = ( {
+	hsla,
+	enableAlpha,
+	onChange,
+	onInteractionStart,
+	onInteractionEnd,
+}: PickerProps ) => {
+	const [ hsva, setHsva ] = useState< HsvaColor >( () => toHsva( hsla ) );
+	// Last HSLA emitted by this picker — skip echoing it back into HSVA.
+	const pickerOriginHslaRef = useRef< HslaColor | null >( null );
+	// Previous parent HSLA — detect which channel changed on achromatic sync.
+	const prevHslaRef = useRef< HslaColor >( hsla );
+	// Pointer/touch drag: never sync from HSLA mid-gesture (origin match alone
+	// can fail across rapid frames when parent gradient state re-renders).
+	const isPointerInteractingRef = useRef( false );
+
+	useEffect( () => {
+		if ( isPointerInteractingRef.current ) {
+			// Keep prevHsla in lockstep with parent updates during the gesture
+			// so a post-drag HSL sibling edit is not compared against pre-drag
+			// HSLA and mistaken for a saturation change.
+			prevHslaRef.current = hsla;
+			return;
+		}
+		if (
+			pickerOriginHslaRef.current &&
+			isSameHsla( pickerOriginHslaRef.current, hsla )
+		) {
+			prevHslaRef.current = hsla;
+			return;
+		}
+		pickerOriginHslaRef.current = null;
+		setHsva( ( prev ) =>
+			toHsvaFromHsla( hsla, prev, prevHslaRef.current )
+		);
+		prevHslaRef.current = hsla;
+	}, [ hsla ] );
+
+	// Inline handlers so refs are not passed into a helper during render
+	// (react-hooks/refs). Pointer capture also keeps drag working over iframes.
+	const pointerCaptureProps = {
+		onPointerDown( { currentTarget, pointerId }: PointerEvent ) {
+			isPointerInteractingRef.current = true;
+			onInteractionStart?.();
+			currentTarget.setPointerCapture( pointerId );
+		},
+		onPointerUp( { currentTarget, pointerId }: PointerEvent ) {
+			currentTarget.releasePointerCapture( pointerId );
+			isPointerInteractingRef.current = false;
+			onInteractionEnd?.();
+		},
+		onPointerCancel( { currentTarget, pointerId }: PointerEvent ) {
+			currentTarget.releasePointerCapture( pointerId );
+			isPointerInteractingRef.current = false;
+			onInteractionEnd?.();
+		},
+	};
+
+	const handleChange = ( next: HsvaColor ) => {
+		setHsva( next );
+		const nextHsla: HslaColor = { ...colord( next ).toHsl(), a: next.a };
+		pickerOriginHslaRef.current = nextHsla;
+		onChange( nextHsla );
+	};
 
-export const Picker = ( { hsla, enableAlpha, onChange }: PickerProps ) => {
 	if ( enableAlpha ) {
 		return (
-			<HslaColorPicker
-				color={ hsla }
-				onChange={ onChange }
+			<HsvaColorPicker
+				color={ hsva }
+				onChange={ handleChange }
 				{ ...pointerCaptureProps }
 			/>
 		);
 	}
 
+	// HsvColorPicker's equality checks enumerate own keys — never pass `a`,
+	// or every parent re-render looks like an external color change and the
+	// pointer jitters while dragging.
+	const hsv = { h: hsva.h, s: hsva.s, v: hsva.v };
+
 	return (
-		<HslColorPicker
-			color={ hsla }
-			onChange={ ( nextColor ) => {
-				onChange( { ...nextColor, a: hsla.a } );
+		<HsvColorPicker
+			color={ hsv }
+			onChange={ ( next ) => {
+				handleChange( { ...next, a: hsva.a } );
 			} }
 			{ ...pointerCaptureProps }
 		/>