ui/CollapsibleCard: Default Header to a div wrapper

The right heading level depends on the surrounding document outline, so
let consumers opt into heading semantics via render={ <h2 /> } instead
of defaulting to h3. Addresses review feedback.

Author: ciampo

packages/ui/CHANGELOG.md

@@ -8,7 +8,7 @@
 -   `Select`: `Select.Item` values that are empty strings no longer render with placeholder styling on the trigger. Use the new `placeholder` prop on `Select.Trigger`, or a `null` item value, instead ([#78076](https://github.com/WordPress/gutenberg/pull/78076)).
 -   `Select`: `Select.Trigger` now renders a default `"Select"` placeholder when no value is selected, where it previously rendered empty ([#78076](https://github.com/WordPress/gutenberg/pull/78076)).
 -   `Select`: `Select.Item` no longer renders its `value` as fallback item content. Pass item content explicitly as `children`. Migrate `<Select.Item value="Foo" />` to `<Select.Item value="Foo">Foo</Select.Item>` ([#77861](https://github.com/WordPress/gutenberg/pull/77861)).
--   `CollapsibleCard.Header`: Now renders an `<h3>` element by default (was `<div>`) so each card contributes to the document outline. Pass `render={ <h2 /> }` (or another heading level) to change the level, or `render={ <div /> }` to opt out. Forwarded props (`className`, `style`, `aria-*`, `data-*`) and `ref` now land on the outer heading wrapper instead of the inner click-target div; `ref` widens from `HTMLDivElement` to `HTMLHeadingElement` ([#77962](https://github.com/WordPress/gutenberg/pull/77962)).
+-   `CollapsibleCard.Header`: Now renders an outer `<div>` wrapper around the trigger. Forwarded props (`className`, `aria-*`, `data-*`) and `ref` land on this outer wrapper instead of the inner click-target div ([#77962](https://github.com/WordPress/gutenberg/pull/77962)).
 
 ### New Features
 
@@ -27,7 +27,7 @@
 -   `Select`: Add a `placeholder` prop to `Select.Trigger`, and support `null` item values for clearable placeholder options ([#78076](https://github.com/WordPress/gutenberg/pull/78076)).
 -   `Drawer`: Fade the popup elevation shadow alongside the slide ([#77800](https://github.com/WordPress/gutenberg/pull/77800)).
 -   `Drawer`: Allow mouse-drag swipe-dismiss in the popup-edge padding gutter ([#77800](https://github.com/WordPress/gutenberg/pull/77800)).
--   `CollapsibleCard`: Each card now contributes a heading to the document outline by default, following the W3C APG accordion pattern (heading wraps button) ([#77962](https://github.com/WordPress/gutenberg/pull/77962)).
+-   `CollapsibleCard.Header`: Pass `render={ <h2 /> }` (or any of `<h1>`–`<h6>`) to wrap the trigger in a heading and contribute to the document outline, following the W3C APG accordion pattern (heading wraps button) ([#77962](https://github.com/WordPress/gutenberg/pull/77962)).
 
 ## 0.12.0 (2026-04-29)
 

packages/ui/src/collapsible-card/header.tsx

@@ -16,18 +16,19 @@ import type { HeaderProps } from './types';
  * toggle trigger — clicking anywhere on it expands or collapses the
  * card's content.
  *
- * Renders an `<h3>` element by default so each card contributes to the
- * document outline. Pass `render` to change the heading level (e.g.
- * `render={ <h2 /> }`) or to opt out of heading semantics entirely
- * (`render={ <div /> }`) when no outline contribution is desired.
+ * Defaults to a `<div>` wrapper around the trigger. Since the right heading
+ * level depends on the surrounding document outline, the consumer is
+ * expected to opt in to heading semantics. Pass `render` to wrap the
+ * trigger in a heading (e.g. `render={ <h2 /> }`), following the W3C APG
+ * accordion pattern (heading wraps button).
  *
  * Avoid placing interactive elements (buttons, links, inputs) inside the
  * header, since the entire area is clickable and their events will bubble
  * to trigger the collapse toggle.
  */
-export const Header = forwardRef< HTMLHeadingElement, HeaderProps >(
+export const Header = forwardRef< HTMLDivElement, HeaderProps >(
 	function CollapsibleCardHeader(
-		{ children, className, style, render, ...restProps },
+		{ children, className, render, ...restProps },
 		ref
 	) {
 		const [ descriptionId, setDescriptionId ] = useState< string >();
@@ -38,16 +39,15 @@ export const Header = forwardRef< HTMLHeadingElement, HeaderProps >(
 		);
 
 		return useRender( {
-			defaultTagName: 'h3',
+			defaultTagName: 'div',
 			render,
 			ref,
-			props: mergeProps< 'h3' >( restProps, {
+			props: mergeProps< 'div' >( restProps, {
 				className: clsx(
 					defenseStyles.heading,
 					styles[ 'heading-wrapper' ],
 					className
 				),
-				style,
 				children: (
 					<HeaderDescriptionIdContext.Provider value={ contextValue }>
 						<Collapsible.Trigger

packages/ui/src/collapsible-card/stories/index.story.tsx

@@ -166,10 +166,11 @@ export const Stacked: Story = {
 };
 
 /**
- * `CollapsibleCard.Header` renders an `<h3>` by default so the card
- * contributes to the document outline. Use the `render` prop to change the
- * heading level (e.g. `render={ <h2 /> }`) or to opt out of heading
- * semantics entirely (`render={ <div /> }`).
+ * `CollapsibleCard.Header` renders a `<div>` wrapper by default. Pass an
+ * `<h1>`–`<h6>` React element to the `render` prop to wrap the trigger in
+ * a heading and contribute to the document outline. The right level
+ * depends on the surrounding outline, so the consumer is expected to opt
+ * in.
  */
 export const WithHeadingElement: Story = {
 	parameters: { controls: { disable: true } },
@@ -193,24 +194,25 @@ export const WithHeadingElement: Story = {
 				</CollapsibleCard.Content>
 			</CollapsibleCard.Root>
 			<CollapsibleCard.Root>
-				<CollapsibleCard.Header>
-					<Card.Title>Heading level 3 (default)</Card.Title>
+				<CollapsibleCard.Header render={ <h3 /> }>
+					<Card.Title>Heading level 3</Card.Title>
 				</CollapsibleCard.Header>
 				<CollapsibleCard.Content>
 					<Text>
-						Without a render prop, the header defaults to an h3
-						element.
+						Pass any of h1–h6 to choose the level that fits the
+						surrounding document outline.
 					</Text>
 				</CollapsibleCard.Content>
 			</CollapsibleCard.Root>
 			<CollapsibleCard.Root>
-				<CollapsibleCard.Header render={ <div /> }>
-					<Card.Title>No heading semantics</Card.Title>
+				<CollapsibleCard.Header>
+					<Card.Title>No heading (default)</Card.Title>
 				</CollapsibleCard.Header>
 				<CollapsibleCard.Content>
 					<Text>
-						Passing a div React element to the render prop opts out
-						of heading semantics entirely.
+						Without a render prop, the header wraps the trigger in a
+						plain div and does not contribute to the document
+						outline.
 					</Text>
 				</CollapsibleCard.Content>
 			</CollapsibleCard.Root>

packages/ui/src/collapsible-card/style.module.css

@@ -2,11 +2,13 @@
 
 @layer wp-ui-components {
 	/*
-	 * Style overrides for the outer heading wrapper rendered by
-	 * `CollapsibleCard.Header` (defaults to `<h3>`). Combined with
-	 * `defenseStyles.heading` so the unlayered defense class beats wp-admin's
-	 * bare `h2`/`h3`/etc. selectors. Keeps the wrapper visually transparent so
-	 * UA and host stylesheets don't bleed into the inner trigger.
+	 * Style overrides for the outer wrapper rendered by `CollapsibleCard.Header`
+	 * (defaults to `<div>`, but consumers can opt into a heading level via
+	 * `render={ <h2 /> }` etc.). Combined with `defenseStyles.heading` so that,
+	 * when the wrapper renders as an h1–h6, the unlayered defense class beats
+	 * wp-admin's bare `h2`/`h3`/etc. selectors. Keeps the wrapper visually
+	 * transparent so UA and host stylesheets don't bleed into the inner
+	 * trigger.
 	 */
 	.heading-wrapper {
 		--_gcd-heading-color: inherit;

packages/ui/src/collapsible-card/test/index.test.tsx

@@ -8,7 +8,7 @@ describe( 'CollapsibleCard', () => {
 	describe( 'basic behaviour', () => {
 		it( 'forwards ref', () => {
 			const rootRef = createRef< HTMLDivElement >();
-			const headerRef = createRef< HTMLHeadingElement >();
+			const headerRef = createRef< HTMLDivElement >();
 			const contentRef = createRef< HTMLDivElement >();
 
 			render(
@@ -23,7 +23,7 @@ describe( 'CollapsibleCard', () => {
 			);
 
 			expect( rootRef.current ).toBeInstanceOf( HTMLDivElement );
-			expect( headerRef.current ).toBeInstanceOf( HTMLHeadingElement );
+			expect( headerRef.current ).toBeInstanceOf( HTMLDivElement );
 			expect( contentRef.current ).toBeInstanceOf( HTMLDivElement );
 		} );
 
@@ -179,8 +179,8 @@ describe( 'CollapsibleCard', () => {
 		} );
 	} );
 
-	describe( 'heading wrapper', () => {
-		it( 'renders an `<h3>` heading wrapping the trigger by default', () => {
+	describe( 'header wrapper', () => {
+		it( 'does not contribute a heading to the document outline by default', () => {
 			render(
 				<CollapsibleCard.Root>
 					<CollapsibleCard.Header>
@@ -189,17 +189,15 @@ describe( 'CollapsibleCard', () => {
 				</CollapsibleCard.Root>
 			);
 
-			const heading = screen.getByRole( 'heading', {
-				level: 3,
-				name: 'Title',
-			} );
-			expect( heading ).toBeVisible();
 			expect(
-				within( heading ).getByRole( 'button', { name: 'Title' } )
+				screen.queryByRole( 'heading', { name: 'Title' } )
+			).not.toBeInTheDocument();
+			expect(
+				screen.getByRole( 'button', { name: 'Title' } )
 			).toBeVisible();
 		} );
 
-		it( 'renders the heading at a different level via `render`', () => {
+		it( 'wraps the trigger in a heading via `render`', () => {
 			render(
 				<CollapsibleCard.Root>
 					<CollapsibleCard.Header render={ <h2 /> }>
@@ -218,41 +216,25 @@ describe( 'CollapsibleCard', () => {
 			).toBeVisible();
 		} );
 
-		it( 'opts out of heading semantics with `render={ <div /> }`', () => {
-			render(
-				<CollapsibleCard.Root>
-					<CollapsibleCard.Header render={ <div /> }>
-						<Card.Title>Title</Card.Title>
-					</CollapsibleCard.Header>
-				</CollapsibleCard.Root>
-			);
-
-			expect(
-				screen.queryByRole( 'heading', { name: 'Title' } )
-			).not.toBeInTheDocument();
-			expect(
-				screen.getByRole( 'button', { name: 'Title' } )
-			).toBeVisible();
-		} );
-
-		it( 'forwards `className` to the outer heading wrapper', () => {
+		it( 'forwards `className` and other props to the outer wrapper', () => {
 			render(
 				<CollapsibleCard.Root>
 					<CollapsibleCard.Header
-						className="custom-heading"
+						className="custom-header"
 						data-testid="header"
 					>
 						<Card.Title>Title</Card.Title>
 					</CollapsibleCard.Header>
 				</CollapsibleCard.Root>
 			);
 
-			const heading = screen.getByRole( 'heading', {
-				level: 3,
-				name: 'Title',
-			} );
-			expect( heading ).toHaveClass( 'custom-heading' );
-			expect( heading ).toHaveAttribute( 'data-testid', 'header' );
+			const wrapper = screen.getByTestId( 'header' );
+			expect( wrapper ).toHaveClass( 'custom-header' );
+			// The forwarded attributes land on the outer wrapper, not the
+			// inner button trigger.
+			expect(
+				within( wrapper ).getByRole( 'button', { name: 'Title' } )
+			).not.toHaveAttribute( 'data-testid' );
 		} );
 	} );
 
@@ -282,11 +264,6 @@ describe( 'CollapsibleCard', () => {
 				'aria-describedby',
 				descriptionElement.id
 			);
-
-			// aria-describedby must be on the inner button (which is what's
-			// being described), not on the outer heading wrapper.
-			const heading = screen.getByRole( 'heading', { name: 'Settings' } );
-			expect( heading ).not.toHaveAttribute( 'aria-describedby' );
 		} );
 
 		it( 'marks the description content as aria-hidden', () => {

packages/ui/src/collapsible-card/types.ts

@@ -30,7 +30,7 @@ export interface RootProps extends ComponentProps< 'div' > {
 	disabled?: boolean;
 }
 
-export interface HeaderProps extends ComponentProps< 'h3' > {
+export interface HeaderProps extends ComponentProps< 'div' > {
 	/**
 	 * The content to be rendered inside the header.
 	 */