@wordpress/components 40.0.0 → 40.1.1-next.v.202609031004.0

package/build-types/tools-panel/types.d.ts

@@ -93,6 +93,16 @@ export type ToolsPanelHeaderProps = {
     toggleItem: (label: string) => void;
 };
 export type ToolsPanelItem = {
+    /**
+     * For optional items only, this determines whether the item is shown on
+     * first render even when `hasValue()` returns `false`.
+     *
+     * An item is always shown while it has a value, so this only controls the
+     * initial state of items without one.
+     *
+     * @default false
+     */
+    defaultShown?: boolean;
     /**
      * This is called when building the `ToolsPanel` menu to determine the
      * item's initial checked state.
@@ -115,6 +125,27 @@ export type ToolsPanelItem = {
      * panel.
      */
     label: string;
+    /**
+     * A callback executed when the user shows or hides the item via the
+     * `ToolsPanel` menu, passed `true` when it was shown and `false` when it
+     * was hidden.
+     *
+     * Unlike `onDeselect`, this fires whether or not the item has a value, and
+     * only in response to an explicit menu action. Visibility changes with
+     * another cause do not trigger it, such as an item becoming visible
+     * because it received a value or because `defaultShown` was set, or
+     * hiding because `Reset all` ran.
+     *
+     * Items flagged with `isShownByDefault` are always visible and stay so when
+     * toggled off, so this is never called for them.
+     *
+     * A single menu action may also call `onSelect` or `onDeselect`, which are
+     * unchanged. Showing an item without a value calls this with `true` and
+     * `onSelect`; hiding an item that has a value calls this with `false` and
+     * `onDeselect`. Use this callback to track visibility and `onDeselect` to
+     * reset a value, rather than treating them as interchangeable.
+     */
+    onShownChange?: (isShown: boolean) => void;
     /**
      * Panel items will ensure they are only registering with their intended panel
      * by comparing the `panelId` props set on both the item and the panel itself,
@@ -147,6 +178,18 @@ export type ToolsPanelItemProps = ToolsPanelItem & {
      */
     resetAllFilter?: ResetAllFilter;
 };
+/**
+ * The shape of an item as it is held in `ToolsPanel` state. It extends
+ * `ToolsPanelItem` with the data the panel needs but that isn't part of the
+ * item's own API surface.
+ */
+export type RegisteredToolsPanelItem = ToolsPanelItem & {
+    /**
+     * The item's `resetAllFilter`, collected at registration time so the panel
+     * doesn't need a second round of effects to gather them.
+     */
+    resetAllFilter?: ResetAllFilter;
+};
 export type ToolsPanelMenuItemKey = 'default' | 'optional';
 export type ToolsPanelMenuItems = {
     [menuItemKey in ToolsPanelMenuItemKey]: {
@@ -157,11 +200,17 @@ export type ToolsPanelContext = {
     panelId?: string | null;
     menuItems: ToolsPanelMenuItems;
     hasMenuItems: boolean;
-    registerPanelItem: (item: ToolsPanelItem) => void;
-    deregisterPanelItem: (label: string) => void;
+    registerPanelItem: (item: RegisteredToolsPanelItem) => void;
+    deregisterPanelItem: (label: string, item?: RegisteredToolsPanelItem) => void;
     registerResetAllFilter: (filter: ResetAllFilter) => void;
     deregisterResetAllFilter: (filter: ResetAllFilter) => void;
-    flagItemCustomization: (value: boolean, label: string, group?: ToolsPanelMenuItemKey) => void;
+    flagItemCustomization: (value: boolean, label: string, 
+    /**
+     * Ignored, and kept only so that existing three argument callers
+     * still typecheck. The group a value lands in now follows from the
+     * registered item's `isShownByDefault` rather than from the caller.
+     */
+    group?: ToolsPanelMenuItemKey) => void;
     isResetting: boolean;
     shouldRenderPlaceholderItems: boolean;
     areAllOptionalControlsHidden: boolean;
@@ -175,11 +224,5 @@ export type ToolsPanelControlsGroupProps = {
     items: [string, boolean][];
     toggleItem: (label: string) => void;
 };
-export type ToolsPanelMenuItemsConfig = {
-    panelItems: ToolsPanelItem[];
-    shouldReset: boolean;
-    currentMenuItems?: ToolsPanelMenuItems;
-    menuItemOrder: string[];
-};
 export {};
 //# sourceMappingURL=types.d.ts.map

package/build-types/tools-panel/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools-panel/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools-panel/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "40.0.0",
+	"version": "40.1.1-next.v.202609031004.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -62,27 +62,27 @@
 		"@types/gradient-parser": "^1.1.0",
 		"@types/highlight-words-core": "^1.2.1",
 		"@use-gesture/react": "^10.3.1",
-		"@wordpress/a11y": "^4.54.0",
-		"@wordpress/base-styles": "^13.0.0",
-		"@wordpress/compose": "^8.7.0",
-		"@wordpress/date": "^5.54.0",
-		"@wordpress/deprecated": "^4.54.0",
-		"@wordpress/dom": "^4.54.0",
-		"@wordpress/element": "^8.6.0",
-		"@wordpress/escape-html": "^3.54.0",
-		"@wordpress/hooks": "^4.54.0",
-		"@wordpress/html-entities": "^4.54.0",
-		"@wordpress/i18n": "^6.27.0",
-		"@wordpress/icons": "^15.5.0",
-		"@wordpress/is-shallow-equal": "^5.54.0",
-		"@wordpress/kebab-case": "^1.1.0",
-		"@wordpress/keycodes": "^4.54.0",
-		"@wordpress/primitives": "^4.54.0",
-		"@wordpress/private-apis": "^1.54.0",
-		"@wordpress/rich-text": "^7.54.0",
-		"@wordpress/style-runtime": "^0.10.0",
-		"@wordpress/ui": "^0.21.0",
-		"@wordpress/warning": "^3.54.0",
+		"@wordpress/a11y": "^4.54.1-next.v.202609031004.0",
+		"@wordpress/base-styles": "^13.1.1-next.v.202609031004.0",
+		"@wordpress/compose": "^8.7.2-next.v.202609031004.0",
+		"@wordpress/date": "^5.54.1-next.v.202609031004.0",
+		"@wordpress/deprecated": "^4.54.1-next.v.202609031004.0",
+		"@wordpress/dom": "^4.54.1-next.v.202609031004.0",
+		"@wordpress/element": "^8.6.2-next.v.202609031004.0",
+		"@wordpress/escape-html": "^3.54.1-next.v.202609031004.0",
+		"@wordpress/hooks": "^4.54.1-next.v.202609031004.0",
+		"@wordpress/html-entities": "^4.54.1-next.v.202609031004.0",
+		"@wordpress/i18n": "^6.27.1-next.v.202609031004.0",
+		"@wordpress/icons": "^16.0.1-next.v.202609031004.0",
+		"@wordpress/is-shallow-equal": "^5.54.1-next.v.202609031004.0",
+		"@wordpress/kebab-case": "^1.1.1-next.v.202609031004.0",
+		"@wordpress/keycodes": "^4.54.1-next.v.202609031004.0",
+		"@wordpress/primitives": "^4.54.2-next.v.202609031004.0",
+		"@wordpress/private-apis": "^1.54.2-next.v.202609031004.0",
+		"@wordpress/rich-text": "^7.55.1-next.v.202609031004.0",
+		"@wordpress/style-runtime": "^0.10.1-next.v.202609031004.0",
+		"@wordpress/ui": "^0.22.1-next.v.202609031004.0",
+		"@wordpress/warning": "^3.54.1-next.v.202609031004.0",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.9.3",
@@ -111,11 +111,12 @@
 		"@testing-library/user-event": "^14.6.1",
 		"@types/jest": "^30.0.0",
 		"@types/react-dom": "^18.3.1",
-		"@wordpress/jest-console": "^9.2.0",
+		"@wordpress/jest-console": "^9.2.2-next.v.202609031004.0",
 		"@wordpress/stylelint-tools": "file:../../tools/stylelint",
 		"snapshot-diff": "^0.10.0",
 		"storybook": "^10.5.3",
-		"timezone-mock": "^1.3.6"
+		"timezone-mock": "^1.3.6",
+		"vitest": "^4.1.10"
 	},
 	"peerDependencies": {
 		"@types/react": "^18 || ^19",
@@ -130,5 +131,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "5ef24f60261976bb198ad035db24bf81c1fb92b4"
+	"gitHead": "7275d6c6d93b542fca3cd98cdb9c7344ddd11e19"
 }

package/src/angle-picker-control/style.module.scss

@@ -31,7 +31,7 @@
 	border-radius: $radius-round;
 	box-sizing: border-box;
 	display: block;
-	/* stylelint-disable-next-line plugin/use-logical-properties-and-values -- Geometric centering */
+	/* stylelint-disable-next-line logical-css/require-logical-properties -- Geometric centering */
 	left: 50%;
 	top: 4px;
 	transform: translateX(-50%);

package/src/autocomplete/test/get-autocomplete-match.ts

@@ -1,3 +1,4 @@
+import { describe, expect, it, vi } from 'vitest';
 import { getAutocompleteMatch } from '../get-autocomplete-match';
 import type { WPCompleter } from '../types';
 
@@ -174,7 +175,7 @@ describe( 'getAutocompleteMatch', () => {
 	} );
 
 	it( 'should pass correct before/after text to allowContext', () => {
-		const allowContext = jest.fn().mockReturnValue( true );
+		const allowContext = vi.fn().mockReturnValue( true );
 		const completers = [
 			createCompleter( {
 				triggerPrefix: '@',

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

@@ -19,9 +19,9 @@ const meta: Meta< typeof BaseControl > = {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
 		componentStatus: {
-			status: 'recommended',
+			status: 'not-recommended',
 			whereUsed: 'global',
-			notes: '`BaseControl.VisualLabel` can continue to be used for now. To add labels and descriptions semantically, use [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) in `@wordpress/ui`.',
+			notes: 'Use [`Field`](?path=/docs/design-system-components-form-primitives-field--docs) from `@wordpress/ui` instead. For a purely visual label outside `Field.Root`, use `Field.VisualLabel`. For a group legend, use [`Fieldset`](?path=/docs/design-system-components-form-primitives-fieldset--docs) and `Fieldset.Legend`.',
 		},
 	},
 };

package/src/border-box-control/border-box-control/README.md

@@ -103,7 +103,9 @@ Provides control over whether the label will only be visible to screen readers.
 
 ### `label`: `string`
 
-If provided, a label will be generated using this as the content.
+If provided, a label will be generated using this as the content. A visible
+label is rendered in a row alongside the linked/unlinked toggle; when there is
+no visible label the toggle is rendered beside the border inputs instead.
 
 _Whether it is visible only to screen readers is controlled via
 `hideLabelFromVision`._
@@ -130,9 +132,9 @@ The available base placements are 'top', 'right', 'bottom', 'left'. Each of thes
 
 -   Required: No
 
-### `popoverOffset`: `number`
+### `popoverOffset`: `number | { mainAxis?: number; crossAxis?: number }`
 
-The space between the popover and the control wrapper.
+The space between the popover and the control wrapper. A number displaces the popover along its main axis; pass an object to also displace it along its cross axis.
 
 -   Required: No
 

package/src/border-box-control/border-box-control/component.tsx

@@ -1,10 +1,11 @@
 import { __ } from '@wordpress/i18n';
 import { useMemo, useState } from '@wordpress/element';
-import { useMergeRefs } from '@wordpress/compose';
+import { useInstanceId, useMergeRefs } from '@wordpress/compose';
 import BorderBoxControlLinkedButton from '../border-box-control-linked-button';
 import BorderBoxControlSplitControls from '../border-box-control-split-controls';
 import { BorderControl } from '../../border-control';
-import { StyledLabel } from '../../base-control/styles/base-control-styles';
+import BaseControl from '../../base-control';
+import { Grid } from '../../grid';
 import { View } from '../../view';
 import { VisuallyHidden } from '../../visually-hidden';
 import type { WordPressComponentProps } from '../../context';
@@ -16,17 +17,22 @@ import type {
 	BorderControlProps,
 } from '../../border-control/types';
 
-const BorderLabel = ( props: LabelProps ) => {
-	const { label, hideLabelFromVision } = props;
+const BorderLabel = ( props: LabelProps & { id?: string } ) => {
+	const { id, label, hideLabelFromVision } = props;
 
 	if ( ! label ) {
 		return null;
 	}
 
+	// The visible label is rendered as `BaseControl.VisualLabel` so it carries
+	// the stable `.components-base-control__label` className consumers style
+	// against; `StyledLabel` is an emotion component with a generated one.
 	return hideLabelFromVision ? (
-		<VisuallyHidden as="label">{ label }</VisuallyHidden>
+		<VisuallyHidden as="span" id={ id }>
+			{ label }
+		</VisuallyHidden>
 	) : (
-		<StyledLabel>{ label }</StyledLabel>
+		<BaseControl.VisualLabel id={ id }>{ label }</BaseControl.VisualLabel>
 	);
 };
 
@@ -42,6 +48,8 @@ const UnconnectedBorderBoxControl = (
 		enableAlpha,
 		enableStyle,
 		hasMixedBorders,
+		hasVisibleLabel,
+		headerClassName,
 		hideLabelFromVision,
 		isLinked,
 		label,
@@ -55,9 +63,27 @@ const UnconnectedBorderBoxControl = (
 		toggleLinked,
 		wrapperClassName,
 		__experimentalIsRenderedInSidebar,
+		'aria-label': ariaLabel,
+		'aria-labelledby': ariaLabelledBy,
 		...otherProps
 	} = useBorderBoxControl( props );
 
+	// The label names the group of border controls rather than a single input,
+	// so it is associated via `aria-labelledby` instead of `htmlFor`.
+	const generatedLabelId = useInstanceId(
+		BorderBoxControl,
+		'border-box-control-label'
+	);
+
+	// A consumer-provided accessible name takes precedence, so the generated
+	// relationship is only used as a fallback. Where an external name wins,
+	// the unused ID is left off the internal label. Empty values are treated
+	// as absent, matching the accessible name computation, which skips an
+	// empty `aria-label` or `aria-labelledby` rather than resolving a name
+	// from it.
+	const labelId =
+		label && ! ariaLabel && ! ariaLabelledBy ? generatedLabelId : undefined;
+
 	// Use internal state instead of a ref to make sure that the component
 	// re-renders when the popover's anchor updates.
 	const [ popoverAnchor, setPopoverAnchor ] = useState< Element | null >(
@@ -80,12 +106,46 @@ const UnconnectedBorderBoxControl = (
 		);
 
 	const mergedRef = useMergeRefs( [ setPopoverAnchor, forwardedRef ] );
+
 	return (
-		<View className={ className } { ...otherProps } ref={ mergedRef }>
-			<BorderLabel
-				label={ label }
-				hideLabelFromVision={ hideLabelFromVision }
-			/>
+		<View
+			className={ className }
+			// Whichever naming source wins, it describes the border controls
+			// as a whole, so the wrapper needs a role for that accessible
+			// name to attach to. Without a name there is no group to expose.
+			role={ label || ariaLabel || ariaLabelledBy ? 'group' : undefined }
+			aria-label={ ariaLabel }
+			aria-labelledby={ ariaLabelledBy ?? labelId }
+			{ ...otherProps }
+			ref={ mergedRef }
+		>
+			{ hasVisibleLabel ? (
+				// The toggle shares the label's row so that it lines up with
+				// the equivalent toggle on sibling controls, e.g. the border
+				// radius one.
+				<Grid
+					className={ headerClassName }
+					columns={ 2 }
+					templateColumns="1fr min-content"
+					alignment="center"
+				>
+					<BorderLabel
+						id={ labelId }
+						label={ label }
+						hideLabelFromVision={ hideLabelFromVision }
+					/>
+					<BorderBoxControlLinkedButton
+						onClick={ toggleLinked }
+						isLinked={ isLinked }
+					/>
+				</Grid>
+			) : (
+				<BorderLabel
+					id={ labelId }
+					label={ label }
+					hideLabelFromVision={ hideLabelFromVision }
+				/>
+			) }
 			<View className={ wrapperClassName }>
 				{ isLinked ? (
 					<BorderControl
@@ -123,10 +183,14 @@ const UnconnectedBorderBoxControl = (
 						}
 					/>
 				) }
-				<BorderBoxControlLinkedButton
-					onClick={ toggleLinked }
-					isLinked={ isLinked }
-				/>
+				{ /* With no label row to join, the toggle sits alongside the
+				     inputs instead. */ }
+				{ ! hasVisibleLabel && (
+					<BorderBoxControlLinkedButton
+						onClick={ toggleLinked }
+						isLinked={ isLinked }
+					/>
+				) }
 			</View>
 		</View>
 	);
@@ -136,6 +200,10 @@ const UnconnectedBorderBoxControl = (
  * An input control for the color, style, and width of the border of a box. The
  * border can be customized as a whole, or individually for each side of the box.
  *
+ * The controls are exposed as a group named by the `label` prop. Passing
+ * `aria-labelledby` or `aria-label` names the group instead, taking precedence
+ * over `label`; with none of the three, the wrapper is not exposed as a group.
+ *
  * ```jsx
  * import { BorderBoxControl } from '@wordpress/components';
  * import { __ } from '@wordpress/i18n';

package/src/border-box-control/border-box-control/hook.ts

@@ -1,3 +1,4 @@
+import clsx from 'clsx';
 import { useState } from '@wordpress/element';
 import styles from '../style.module.scss';
 import {
@@ -23,6 +24,8 @@ export function useBorderBoxControl(
 		onChange,
 		enableAlpha = false,
 		enableStyle = true,
+		hideLabelFromVision,
+		label,
 		value,
 		__experimentalIsRenderedInSidebar = false,
 		// Deprecated props, no longer used.
@@ -31,6 +34,11 @@ export function useBorderBoxControl(
 		...otherProps
 	} = useContextSystem( props, 'BorderBoxControl' );
 
+	// A visible label gives the control a header row to place the linked/
+	// unlinked toggle in, alongside that label. Without one the toggle stays
+	// inside the input wrapper, positioned absolutely.
+	const hasVisibleLabel = !! label && ! hideLabelFromVision;
+
 	const mixedBorders = hasMixedBorders( value );
 	const splitBorders = hasSplitBorders( value );
 
@@ -99,13 +107,23 @@ export function useBorderBoxControl(
 		}
 	};
 
-	const linkedControlClassName = styles[ 'linked-border-control' ];
+	// The linked control reserves an inline-end gutter for the absolutely
+	// positioned toggle. Once the toggle moves up into the header row that
+	// gutter only shortens the input, so drop it.
+	const linkedControlClassName = clsx( styles[ 'linked-border-control' ], {
+		[ styles[ 'linked-border-control-full-width' ] ]: hasVisibleLabel,
+	} );
 	const wrapperClassName = styles.wrapper;
+	const headerClassName = styles.header;
 
 	return {
 		...otherProps,
 		className,
 		colors,
+		hasVisibleLabel,
+		headerClassName,
+		hideLabelFromVision,
+		label,
 		disableUnits: mixedBorders && ! hasWidthValue,
 		enableAlpha,
 		enableStyle,

package/src/border-box-control/stories/index.story.tsx

@@ -79,3 +79,13 @@ Default.args = {
 	label: 'Borders',
 	enableStyle: true,
 };
+
+/**
+ * With no visible label there is no label row for the linked/unlinked toggle to
+ * join, so it is rendered alongside the border inputs instead.
+ */
+export const WithoutLabel = Template.bind( {} );
+WithoutLabel.args = {
+	...Default.args,
+	label: undefined,
+};

package/src/border-box-control/style.module.scss

@@ -1,3 +1,5 @@
+@use "@wordpress/base-styles/variables" as *;
+
 .linked-border-control {
 	/* Preserve the original `&&` specificity so this beats BorderControl's margin reset. */
 	&#{&} {
@@ -6,14 +8,43 @@
 	}
 }
 
+/* No inline-end gutter is needed when the toggle sits in the header row. */
+.linked-border-control-full-width {
+	&#{&} {
+		margin-inline-end: 0;
+	}
+}
+
+/* The label row the linked/unlinked toggle joins when a visible label is
+   rendered. Laid out as a content-driven grid like `BoxControl`'s label row, so
+   a label that wraps grows the row rather than overflowing a fixed height. */
+.header {
+	/* The row is as tall as the toggle (24px, `Button` `size="small"`), so 4px
+	   here leaves the same 28px between label and inputs as the sibling
+	   controls, which instead pair a fixed 16px row with a 12px margin. */
+	margin-bottom: $grid-unit-05;
+
+	/* The label (a `BaseControl.VisualLabel`, so a `span`) supplies its own
+	   bottom margin as the gap to the input below. In the header row that gap
+	   comes from the row itself, and the margin would both pull the vertically
+	   centred label off centre and pad the row out once the label wraps. */
+	> span {
+		margin-bottom: 0;
+	}
+}
+
 .wrapper {
 	position: relative;
+
+	/* Without a header row the toggle is positioned against the input instead. */
+	.linked-button {
+		position: absolute;
+		top: 8px;
+		inset-inline-end: 0;
+	}
 }
 
 .linked-button {
-	position: absolute;
-	top: 8px;
-	inset-inline-end: 0;
 	line-height: 0;
 }