@wordpress/components 40.0.0 → 40.1.0

package/emotion-to-scss-modules.md

@@ -0,0 +1,149 @@
+# Migrating components from Emotion to SCSS Modules
+
+An Emotion migration should preserve the component's public API, rendered elements, interactions, and resulting styles. Use the existing SCSS Modules and `@wordpress/style-runtime` pipeline. A component migration does not require a new CSS extraction pipeline.
+
+This temporary guide collects the [migration guidelines in #66806](https://github.com/WordPress/gutenberg/issues/66806) and lessons from its merged PRs. The [reference migrations](#reference-migrations) identify useful examples and their limitations. Read the current implementation before copying an older diff. Some merged PRs include explicitly agreed visual or behavior changes that are not part of a mechanical migration.
+
+## Establish the component and consumer contract
+
+Before editing, read the component's types, README, stories, style hooks, and composed primitives. Search for consumers of its exported wrappers, style fragments, and public classes, including outside `packages/components`. A shared style file can serve several components, as with `ColorPalette` and `GradientPicker`.
+
+Record the behavior that needs comparison:
+
+-   Default rendered element, supported `as` targets, refs, prop forwarding, and intrinsic HTML/SVG prop filtering.
+-   Existing public classes and which element adds each one. `useContextSystem` may already supply the root class. Keep legacy spellings, including singular `component-*` names.
+-   Consumer `className` and `style` handling, including spread order and conditional forwarding.
+-   Defaults, variants, nested instances, focus and disabled states, directional styles, and animation state changes.
+-   Selectors that override the component and selectors the component uses to override its children.
+-   Portal and iframe paths, including the document that receives styles.
+
+Capture a focused baseline in Storybook or the editor for the states and consumers at risk. If a regression motivates the migration, reproduce it before changing the implementation. An unchanged isolated story cannot establish compatibility for a consumer that adds its own styles.
+
+### Replace wrappers without changing their role
+
+For `styled( ExistingComponent )`, apply the module class to that same component when it already supplies the needed behavior. Do not replace `Flex`, `Heading`, `Text`, or an input control with a native element just because its wrapper only contained CSS.
+
+For a wrapper that relied directly on Emotion's `as` support, inspect and reuse [`PolymorphicElement`](/packages/components/src/utils/polymorphic-element.tsx). Preserve the original default tag and the component's existing ref and prop contract. `View` already delegates to this utility. A fixed internal element with no exposed polymorphic path can remain a plain element.
+
+Check the current [`WordPressComponent` types](/packages/components/src/context/wordpress-component.ts) instead of introducing another polymorphic type system. [#80705](https://github.com/WordPress/gutenberg/pull/80705) deliberately reduced intrinsic-prop type complexity to control compilation cost. Removing Emotion does not remove the compatibility obligation for `as`.
+
+Keep shared wrappers' private module classes separate from public classes added by callers. In [#80001](https://github.com/WordPress/gutenberg/pull/80001), adding BaseControl label/help classes inside shared wrappers made unrelated consumers match BaseControl selectors; adding classes on both sides also produced duplicates. Test a real `as="legend"` consumer when migrating shared labels, including its visible and visually hidden branches.
+
+`View`'s legacy `css` prop is an explicit exception established by [#79443](https://github.com/WordPress/gutenberg/pull/79443). It remains accepted as a no-op and is consumed before rendering. Do not restore its styling behavior, forward it to the DOM, or treat that decision as permission to remove other props.
+
+## Translate the styles
+
+Follow the package's [styling conventions](/packages/components/CONTRIBUTING.md#styling). Put static declarations in a colocated `style.module.scss`, use kebab-case classes, and compose variants with `clsx`. Use existing semantic attributes and pseudo-classes where appropriate; do not add data attributes solely to select styles.
+
+Name modifier classes for their state and make their owning element clear. When scoping a modifier under a base class, account for the extra specificity. A standalone `.is-active` and `.root.is-active` do not have equal specificity.
+
+Keep fixed values and calculations in Sass when JavaScript does not need them. `ProgressBar` moved its constant indeterminate indicator width into Sass and shared it with the keyframes. CSS Module keyframes can have descriptive local names without component prefixes.
+
+### Preserve dynamic values and overrides
+
+Prefer inline custom properties for genuinely dynamic values, with the actual property declared in the stylesheet. Emotion adds units to many numeric CSS values; custom properties do not. Preserve the original conversion, such as `space( value )` or an explicit `px` suffix, and keep zero distinct from an absent value.
+
+Check these differences before choosing the representation:
+
+-   **Cascade.** Moving `z-index` from a CSS rule to `style.zIndex` prevents ordinary consumer CSS from overriding it. [ZStack's review](https://github.com/WordPress/gutenberg/pull/80514#discussion_r3845479235) led to passing the number through a custom property and keeping `z-index` in the module rule.
+-   **Precedence.** Preserve consumer `style` values and the component's existing override rules. Do not copy a universal spread order from another migration. `Spacer` lets consumer custom properties win; `Flex` supplies its internal variables after the consumer style object. Ordinary inline CSS properties still override stylesheet declarations.
+-   **Inheritance.** Internal custom properties inherit unless reset. Reset them on each instance when nested components must not inherit a parent's values, as in `Spacer`. Do not reset intentionally inherited theme variables.
+-   **Shorthands.** A later longhand with an absent custom property can undo the shorthand result. Preserve the fallback and precedence of all-sides, axis, and individual-side values. Check shorthand-only, longhand-only, and combined inputs, including supported CSS strings. The `Spacer` review caught missing longhand fallbacks.
+-   **Accepted CSS values.** CSS-wide keywords apply to a custom property itself. `--style: inherit; border-style: var(--style, solid)` does not mean `border-style: inherit`. In [#80437](https://github.com/WordPress/gutenberg/pull/80437#discussion_r3608442254), the indicator retained direct `borderStyle` and `borderColor` values and the original `color || fallback` behavior. Check empty strings and CSS-wide values when the API accepts arbitrary CSS. Direct inline properties can be appropriate, but assess their effect on consumer overrides explicitly.
+
+### Preserve direction, tokens, and state changes
+
+Use logical properties where they preserve the intended behavior. Compare LTR and RTL, and relevant writing modes, before changing a physical property. `Surface` exposes physical border props; `TextareaControl` retains `resize: vertical`; `DropdownContentWrapper` offsets the Popover's physical padding. These are reasons for narrow lint suppressions, not a blanket ban on logical properties. `padding: 0` also resets more than `padding-inline: 0`.
+
+Preserve necessary browser declarations and pseudo-elements. Examples include Truncate's `-webkit-box-orient: vertical`, SearchControl's WebKit search decorations, and TextareaControl's placeholder selectors and global dark-theme ancestor.
+
+Prefer equivalent WPDS tokens and existing Sass variables or mixins. Check what they expand to, including fallback values and validated-control accent overrides. A similarly named token can change the color or geometry. Keep intentional visual changes explicit, as in `Surface` and `ToggleGroupControl`, instead of presenting them as style parity.
+
+Compare transitions between states as well as static states. [ProgressBar's review](https://github.com/WordPress/gutenberg/pull/80512#discussion_r3830324726) caught a width transition newly applying when switching to indeterminate mode. Preserve the original animation direction, duration, transition conditions, reduced-motion rules, and forced-colors treatment where present.
+
+## Preserve the winning declarations
+
+CSS Module scoping prevents class-name collisions. It does not control specificity or stylesheet insertion order. The order of class names passed to `clsx` does not control the cascade either.
+
+Compare matched declarations on the component and its consumers:
+
+-   Keep low-specificity defaults overridable. The Divider migration added attribute-selector specificity and broke `CardDivider` and complementary-area border overrides. [#79534](https://github.com/WordPress/gutenberg/pull/79534) wrapped orientation attributes in `:where()` to remove that extra specificity.
+-   Preserve deliberate Emotion `&&` or `&&&` increases. Sass can express these as `.wrapper.wrapper` or `.label.label.label`; raw `&&&` is not valid Dart Sass. ConfirmDialog's doubled selector keeps its overlay above the parent Popover.
+-   Protect every declaration that must beat a still-Emotion-based primitive. ColorPalette initially protected `font-size` and margin but missed `line-height`; Heading's later rule won in the root document. ToolsPanel had a similar heading conflict.
+-   Keep selector relationships and scope. Nesting `.layered > .child` under `.z-stack` adds specificity. Replacing Emotion component interpolation requires checking which real elements the new selector matches.
+-   Mark existing external classes with `:global(...)` inside a CSS Module, for example `:global(.components-panel__row) &`. Do not accidentally hash a legacy class, broaden its matching elements, or add a public class solely to replace an internal selector.
+
+Use the smallest selector change that preserves the required winner. Do not put every rule in `:where()`, increase every selector, or add `!important` to hide an unexplained conflict. Record why a deliberate specificity adjustment is needed.
+
+### Audit remaining Emotion consumers
+
+Removing an Emotion wrapper can expose source-order dependencies in callers that still use `useCx`. Where fragments overlap on a property, shorthand/longhand pair, or nested selector, compose them in one `css()` call before passing them to `cx()`:
+
+```js
+const classes = cx(
+	css( baseStyles, condition && overrideStyles ),
+	className
+);
+```
+
+This is an interim compatibility fix for existing Emotion consumers, not a pattern for newly migrated styles. Do not mechanically combine unrelated fragments. Audit callers outside the migrated directory: [#79443](https://github.com/WordPress/gutenberg/pull/79443) updated several consumers but missed the BorderBoxControl gutter regression fixed in [#79967](https://github.com/WordPress/gutenberg/pull/79967).
+
+Test mixed Emotion/Module composition in both the root and iframe documents when used there. [Scrollable's review](https://github.com/WordPress/gutenberg/pull/80694#discussion_r3845389532) found that `CardBody isScrollable` kept `height: 100%` in an iframe but resolved to `auto` in the root document because insertion order differed.
+
+## Verify CSS delivery and behavior
+
+Reuse existing tests and stories first. Add or extend a test only for a concrete migration risk that existing coverage does not protect. Choose the smallest check that observes the behavior and would fail if it regressed. A behavior-preserving migration may need no new tests. When automated tests cannot observe the real styling path, document a focused before/after browser check instead of adding a test that cannot detect the regression.
+
+[`StyleProvider`](/packages/components/src/style-provider/index.tsx) both supplies an Emotion cache and registers a document with `@wordpress/style-runtime`. Keep the relevant provider and registration path while either responsibility is needed. Removing a component's Emotion import does not make this infrastructure redundant.
+
+For SlotFill or portals, use an attached iframe with a real `contentDocument` and `defaultView`. Assert a computed style in the destination document. A class on the element or a style tag in the parent document does not prove delivery. [#80384](https://github.com/WordPress/gutenberg/pull/80384) pairs a registration test with a Storybook example that renders migrated Spacer styles in an iframe.
+
+Match the evidence to the behavior at risk:
+
+| What needs proof | Suitable evidence |
+| --- | --- |
+| DOM, public classes, refs, props, variants, and interactions | Existing component tests; extend them only for an uncovered integration risk. Assert the actual styled node, including the outer Grid child when an inner wrapper has the same class. |
+| Real SCSS declarations, specificity, custom-property resolution, dimensions, and animation | Storybook or editor comparison using production styles, computed styles, and relevant interactions. Include a consumer override and the affected document/RTL states. |
+| Cross-document registration or a particular mixed-style composition mechanism | Reuse shared registration coverage. Add a component-specific test only for an uncovered registration or composition risk. A small fixture stylesheet can test that mechanism; pair it with a real-style check. |
+
+Jest mocks stylesheet imports. Public-class assertions can protect a compatibility contract; private module-class assertions establish wiring only. Neither proves that the real CSS loads or wins. Do not add class assertions or snapshots solely to mirror the implementation. Do not inject the desired production selector into a test and claim it protects that selector: the test would still pass if the SCSS rule were deleted. This distinction led to removing tests in [#81792](https://github.com/WordPress/gutenberg/pull/81792#discussion_r3811746653).
+
+Keep new tests focused on the migrated component's integration. A wrapper test can protect its `as`, ref, or prop forwarding even when the shared helper is already tested. Do not copy PolymorphicElement's entire filtering suite into every wrapper, duplicate a full editor setup for a small assertion, or introduce a new Storybook testing convention just for the migration. Check the relevant states and combinations from the contract audit; do not generate every prop combination or supported tag. When a real-style assertion is unavailable, state the gap and give reproducible manual steps.
+
+## Complete the migration
+
+Remove obsolete Emotion imports, files, lint/type suppressions, and utilities that become unused because of this migration. Search all consumers before deleting shared constants. Preserve useful comments explaining layout calculations or compatibility workarounds. Leave unrelated cleanup and global Emotion dependencies, Babel wiring, serializers, `useCx`, and the `rtl` utility until their remaining users are gone.
+
+Follow [worktree setup](/docs/contributors/code/getting-started-with-code-contribution.md#set-up-each-worktree) and read the [testing overview](/docs/contributors/code/testing-overview.md) before adding tests. New tests use Vitest; the [migration manifest](/test/unit/test-migration.json) identifies legacy tests still owned by Jest. From the repository root, use the appropriate focused command below, then run lint and the repository gates:
+
+```sh
+npm run test:unit -- <legacy-jest-test-path> --runInBand
+npm run test:unit:vitest -- <vitest-test-path>
+npm run lint:js -- <changed-js-files>
+npm run lint:css
+npm run typecheck
+npm run build
+npm run test:unit:update
+npm run test:unit:vitest:update
+git diff --check
+```
+
+The snapshot updates are for the whole repository because downstream consumers can change. Jest and Vitest own separate suites, so neither command covers both. Review every snapshot change for removed or duplicated public classes, changed elements, forwarded props, and consumer output. Do not accept a snapshot solely because Emotion classes disappeared. Rerun the exact failing file or shard before attributing a broad failure to the migration.
+
+For generated-file verification, start from a clean committed worktree and run the applicable generators and suppression updates. `npm run other:check-local-changes` runs the documentation and theme generators through its npm prehook, then checks the unstaged diff. It does not run every generator or suppression update; consult the current [static-checks workflow](/.github/workflows/static-checks.yml) for those required by the migration. Inspect generated changes before staging them, since staged changes are invisible to the checker. Commit required updates, then repeat the applicable generation and check commands from the clean worktree.
+
+Recheck the final selectors and consumers after the last edit or rebase; a previous visual check does not cover a later specificity change. Preserve newer trunk changes, such as focus-ring updates, when moving declarations out of an old style file.
+
+Follow [package changelog guidance](/docs/contributors/code/managing-packages.md). For production migrations, use the current unreleased section and this PR's link. The merged migrations record the `cx()` composition limitation under **Breaking Changes**, even when normal component usage is visually unchanged. Do not copy an early pilot's `Internal` entry as the only release note. Record any separately agreed behavior change and its verification independently, as #80715 did for Reset focus retention.
+
+## Reference migrations
+
+Choose an example for the risk in the current migration, then check it against current source. The full migration history is maintained in [#66806](https://github.com/WordPress/gutenberg/issues/66806).
+
+| Migration risk | Merged example | What to inspect |
+| --- | --- | --- |
+| Polymorphic wrappers | View, [#79443](https://github.com/WordPress/gutenberg/pull/79443) | Shared polymorphic replacement, legacy `css` no-op, and downstream consumers. |
+| Dynamic spacing | Spacer, [#79449](https://github.com/WordPress/gutenberg/pull/79449) | Nested custom-property resets and shorthand/longhand fallback. |
+| Selector specificity | Divider, [#79444](https://github.com/WordPress/gutenberg/pull/79444), and [#79534](https://github.com/WordPress/gutenberg/pull/79534) | Orientation selectors and the correction that restored consumer overrides. |
+| Mixed Emotion composition | Border controls, [#80437](https://github.com/WordPress/gutenberg/pull/80437) | Overrides, CSS-wide values, and the linked-control gutter. |
+| Root and iframe delivery | Scrollable, [#80694](https://github.com/WordPress/gutenberg/pull/80694) | CardBody height and stylesheet insertion order in each document. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "40.0.0",
+	"version": "40.1.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.55.0",
+		"@wordpress/base-styles": "^13.1.0",
+		"@wordpress/compose": "^8.8.0",
+		"@wordpress/date": "^5.55.0",
+		"@wordpress/deprecated": "^4.55.0",
+		"@wordpress/dom": "^4.55.0",
+		"@wordpress/element": "^8.7.0",
+		"@wordpress/escape-html": "^3.55.0",
+		"@wordpress/hooks": "^4.55.0",
+		"@wordpress/html-entities": "^4.55.0",
+		"@wordpress/i18n": "^6.28.0",
+		"@wordpress/icons": "^16.0.0",
+		"@wordpress/is-shallow-equal": "^5.55.0",
+		"@wordpress/kebab-case": "^1.2.0",
+		"@wordpress/keycodes": "^4.55.0",
+		"@wordpress/primitives": "^4.55.0",
+		"@wordpress/private-apis": "^1.55.0",
+		"@wordpress/rich-text": "^7.55.0",
+		"@wordpress/style-runtime": "^0.11.0",
+		"@wordpress/ui": "^0.22.0",
+		"@wordpress/warning": "^3.55.0",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.9.3",
@@ -106,16 +106,17 @@
 		"@storybook/addon-docs": "^10.5.3",
 		"@storybook/react-vite": "^10.5.3",
 		"@testing-library/dom": "^10.4.1",
-		"@testing-library/jest-dom": "^6.9.1",
-		"@testing-library/react": "^16.3.2",
+		"@testing-library/jest-dom": "^7.0.1",
+		"@testing-library/react": "^16.3.3",
 		"@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.3.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": "^5.0.0"
 	},
 	"peerDependencies": {
 		"@types/react": "^18 || ^19",
@@ -130,5 +131,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "5ef24f60261976bb198ad035db24bf81c1fb92b4"
+	"gitHead": "485f42ae8a1c58ceea18371a507fd4acfa86fbd8"
 }

package/src/alignment-matrix-control/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { describe, expect, it, vi } from 'vitest';
 import { render, screen, waitFor, within } from '@testing-library/react';
 import { press, click } from '@ariakit/test';
 import AlignmentMatrixControl from '..';
@@ -51,7 +52,7 @@ describe( 'AlignmentMatrixControl', () => {
 					'bottom center',
 					'bottom right',
 				] )( '%s', async ( alignment ) => {
-					const spy = jest.fn();
+					const spy = vi.fn();
 
 					await renderAndInitCompositeStore(
 						<AlignmentMatrixControl
@@ -69,7 +70,7 @@ describe( 'AlignmentMatrixControl', () => {
 				} );
 
 				it( 'unless already focused', async () => {
-					const spy = jest.fn();
+					const spy = vi.fn();
 
 					await renderAndInitCompositeStore(
 						<AlignmentMatrixControl
@@ -96,7 +97,7 @@ describe( 'AlignmentMatrixControl', () => {
 					[ 'ArrowDown', 'bottom center' ],
 					[ 'ArrowRight', 'center right' ],
 				] as const )( '%s', async ( keyRef, cellRef ) => {
-					const spy = jest.fn();
+					const spy = vi.fn();
 
 					await renderAndInitCompositeStore(
 						<AlignmentMatrixControl onChange={ spy } />
@@ -117,7 +118,7 @@ describe( 'AlignmentMatrixControl', () => {
 					[ 'ArrowDown', 'bottom right' ],
 					[ 'ArrowRight', 'bottom right' ],
 				] as const )( '%s', async ( keyRef, cellRef ) => {
-					const spy = jest.fn();
+					const spy = vi.fn();
 
 					await renderAndInitCompositeStore(
 						<AlignmentMatrixControl onChange={ spy } />

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/autocomplete/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { describe, expect, it, vi } from 'vitest';
 import { render, screen, renderHook } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { useRef } from '@wordpress/element';
@@ -119,7 +120,7 @@ describe( 'AutocompleterUI', () => {
 		it( 'should call reset function when a click on another element occurs', async () => {
 			const user = userEvent.setup();
 
-			const resetSpy = jest.fn();
+			const resetSpy = vi.fn();
 
 			const autocompleter = {
 				name: 'fruit',

package/src/badge/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import _Badge from '..';
 

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/base-control/test/{index.tsx → index.jsdom.test.tsx}

@@ -1,3 +1,4 @@
+import { describe, expect, it } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import BaseControl from '..';
 import { useBaseControlProps } from '../hooks';

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,
+};