@wordpress/ui 0.12.0 → 0.13.0

package/build-types/tooltip/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/tooltip/stories/index.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,KAAK,OAAO,MAAM,KAAK,CAAC;AAE/B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,OAAO,CAAC,IAAI,CASpC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CASlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CAMnD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CA+BtD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CAkB3D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CAoBvD,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/tooltip/stories/index.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,KAAK,OAAO,MAAM,KAAK,CAAC;AAE/B,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,OAAO,CAAC,IAAI,CAiBpC,CAAC;eACa,IAAI;AAEnB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CASlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CAMnD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CA6CtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CAmB/D,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CAkB3D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAE,OAAO,OAAO,CAAC,IAAI,CAoBvD,CAAC"}

package/build-types/tooltip/stories/usage-guidelines.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-guidelines.story.d.ts","sourceRoot":"","sources":["../../../src/tooltip/stories/usage-guidelines.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAa5D,QAAA,MAAM,IAAI,EAAE,IAMX,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAC;AAEtB;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,KA2B9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,KA0ChC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAYnC,CAAC"}
+{"version":3,"file":"usage-guidelines.story.d.ts","sourceRoot":"","sources":["../../../src/tooltip/stories/usage-guidelines.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAa5D,QAAA,MAAM,IAAI,EAAE,IAWX,CAAC;eACa,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAC;AAEtB;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,KA2B9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,KA0ChC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,KAYnC,CAAC"}

package/build-types/tooltip/types.d.ts

@@ -2,6 +2,7 @@ import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
 import type { Tooltip as _Tooltip } from '@base-ui/react/tooltip';
 import type { ComponentProps } from '../utils/types';
 export type PortalProps = ComponentPropsWithoutRef<typeof _Tooltip.Portal>;
+export type PositionerProps = ComponentPropsWithoutRef<typeof _Tooltip.Positioner>;
 export type RootProps = Pick<_Tooltip.Root.Props, 'disabled' | 'children'>;
 export type ProviderProps = Pick<_Tooltip.Provider.Props, 'delay' | 'children'>;
 export interface TriggerProps extends ComponentProps<'button'> {
@@ -10,7 +11,7 @@ export interface TriggerProps extends ComponentProps<'button'> {
      */
     children?: ReactNode;
 }
-export interface PopupProps extends ComponentProps<'div'>, Pick<_Tooltip.Positioner.Props, 'align' | 'side' | 'sideOffset'> {
+export interface PopupProps extends ComponentProps<'div'> {
     /**
      * The content to be rendered inside the component.
      */
@@ -22,5 +23,13 @@ export interface PopupProps extends ComponentProps<'div'>, Pick<_Tooltip.Positio
      * be ignored.
      */
     portal?: ReactElement<Omit<PortalProps, 'children'>>;
+    /**
+     * Optional positioner element, typically `<Tooltip.Positioner />` with
+     * custom positioning props (`side`, `align`, `sideOffset`, collision
+     * settings, etc.). When omitted, `Tooltip.Popup` uses `Tooltip.Positioner`
+     * with default props. Do not pass `children` on the positioner element;
+     * they would be ignored.
+     */
+    positioner?: ReactElement<Omit<PositionerProps, 'children'>>;
 }
 //# sourceMappingURL=types.d.ts.map

package/build-types/tooltip/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tooltip/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG,wBAAwB,CAAE,OAAO,QAAQ,CAAC,MAAM,CAAE,CAAC;AAE7E,MAAM,MAAM,SAAS,GAAG,IAAI,CAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAE,CAAC;AAE7E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC/B,QAAQ,CAAC,QAAQ,CAAC,KAAK,EACvB,OAAO,GAAG,UAAU,CACpB,CAAC;AAEF,MAAM,WAAW,YAAa,SAAQ,cAAc,CAAE,QAAQ,CAAE;IAC/D;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,UAChB,SAAQ,cAAc,CAAE,KAAK,CAAE,EAC9B,IAAI,CAAE,QAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAE;IACnE;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,CAAE,IAAI,CAAE,WAAW,EAAE,UAAU,CAAE,CAAE,CAAC;CACzD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tooltip/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC/E,OAAO,KAAK,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG,wBAAwB,CAAE,OAAO,QAAQ,CAAC,MAAM,CAAE,CAAC;AAE7E,MAAM,MAAM,eAAe,GAAG,wBAAwB,CACrD,OAAO,QAAQ,CAAC,UAAU,CAC1B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,IAAI,CAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAE,CAAC;AAE7E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC/B,QAAQ,CAAC,QAAQ,CAAC,KAAK,EACvB,OAAO,GAAG,UAAU,CACpB,CAAC;AAEF,MAAM,WAAW,YAAa,SAAQ,cAAc,CAAE,QAAQ,CAAE;IAC/D;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,UAAW,SAAQ,cAAc,CAAE,KAAK,CAAE;IAC1D;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,CAAE,IAAI,CAAE,WAAW,EAAE,UAAU,CAAE,CAAE,CAAC;IAEzD;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,YAAY,CAAE,IAAI,CAAE,eAAe,EAAE,UAAU,CAAE,CAAE,CAAC;CACjE"}

package/build-types/utils/create-overlay-modal-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-overlay-modal-context.d.ts","sourceRoot":"","sources":["../../src/utils/create-overlay-modal-context.tsx"],"names":[],"mappings":"AAEA,KAAK,yBAAyB,CAAE,KAAK,IAAK;IACzC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,yBAAyB,CAAE,KAAK,EAAI,YAAY,EAAE,KAAK;qCAMnE,yBAAyB,CAAE,KAAK,CAAE;;EAgBrC"}
+{"version":3,"file":"create-overlay-modal-context.d.ts","sourceRoot":"","sources":["../../src/utils/create-overlay-modal-context.tsx"],"names":[],"mappings":"AAEA,KAAK,yBAAyB,CAAE,KAAK,IAAK;IACzC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,yBAAyB,CAAE,KAAK,EAAI,YAAY,EAAE,KAAK;IAmBrE,QAAQ,yBAbN,yBAAyB,CAAE,KAAK,CAAE;IAcpC,QAAQ;EAET"}

package/build-types/utils/render-slot-with-children.d.ts

@@ -0,0 +1,24 @@
+import type { ReactElement, ReactNode } from 'react';
+/**
+ * Fills an optional "slot" element prop with content by cloning it and
+ * injecting the given `children`. When `slot` is undefined, the provided
+ * `defaultSlot` is used in its place.
+ *
+ * Shared by overlay `Popup` components for their slot-shaped customization
+ * props (e.g. `portal`, `positioner`), so the merge behavior — defaults,
+ * children injection — stays consistent across all of them.
+ *
+ * Callers should type the slot prop as `ReactElement<Omit<Props, 'children'>>`:
+ * any subtree passed on the slot element is overwritten by `children`.
+ *
+ * @param slot        Optional element from the slot prop (e.g. `<Tooltip.Portal … />`
+ *                    or `<Tooltip.Positioner … />`). When omitted, `defaultSlot`
+ *                    is used. Injected `children` replace any subtree the caller
+ *                    may have passed on the slot element.
+ * @param defaultSlot Unpopulated default element used when `slot` is omitted
+ *                    (e.g. `<Tooltip.Portal />`).
+ * @param children    Content to inject as the slot's children (backdrop,
+ *                    positioner, popup subtree, etc.).
+ */
+export declare function renderSlotWithChildren(slot: ReactElement | undefined, defaultSlot: ReactElement, children: ReactNode): ReactElement;
+//# sourceMappingURL=render-slot-with-children.d.ts.map

package/build-types/utils/render-slot-with-children.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-slot-with-children.d.ts","sourceRoot":"","sources":["../../src/utils/render-slot-with-children.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,YAAY,GAAG,SAAS,EAC9B,WAAW,EAAE,YAAY,EACzB,QAAQ,EAAE,SAAS,GACjB,YAAY,CAEd"}

package/build-types/utils/use-deprioritized-initial-focus.d.ts

@@ -26,7 +26,7 @@ type InitialFocus = _Popover.Popup.Props['initialFocus'];
  * @param props.initialFocus            The consumer-provided `initialFocus` value.
  * @param props.deprioritizedAttributes The data attributes whose elements should be deprioritized.
  */
-export declare function useDeprioritizedInitialFocus({ initialFocus, deprioritizedAttributes, }: {
+export declare function useDeprioritizedInitialFocus({ initialFocus, deprioritizedAttributes }: {
     initialFocus: InitialFocus;
     deprioritizedAttributes: string[];
 }): {

package/build-types/utils/use-deprioritized-initial-focus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-deprioritized-initial-focus.d.ts","sourceRoot":"","sources":["../../src/utils/use-deprioritized-initial-focus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIlE;;;;GAIG;AACH,KAAK,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAE,cAAc,CAAE,CAAC;AAe3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,4BAA4B,CAAE,EAC7C,YAAY,EACZ,uBAAuB,GACvB,EAAE;IACF,YAAY,EAAE,YAAY,CAAC;IAC3B,uBAAuB,EAAE,MAAM,EAAE,CAAC;CAClC;;;EAsCA"}
+{"version":3,"file":"use-deprioritized-initial-focus.d.ts","sourceRoot":"","sources":["../../src/utils/use-deprioritized-initial-focus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIlE;;;;GAIG;AACH,KAAK,YAAY,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAE,cAAc,CAAE,CAAC;AAe3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,4BAA4B,CAAE,EAC7C,YAAY,EACZ,uBAAuB,EACvB,EAAE;IACF,YAAY,EAAE,YAAY,CAAC;IAC3B,uBAAuB,EAAE,MAAM,EAAE,CAAC;CAClC;;;EAsCA"}

package/build-types/visually-hidden/stories/index.story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/visually-hidden/stories/index.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAErC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CAItC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAE,OAAO,cAAc,CAAE,CAAC;AAE/C,eAAO,MAAM,OAAO,EAAE,KAUrB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAgB/B,CAAC"}
+{"version":3,"file":"index.story.d.ts","sourceRoot":"","sources":["../../../src/visually-hidden/stories/index.story.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAErC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CAUtC,CAAC;eACa,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAE,OAAO,cAAc,CAAE,CAAC;AAE/C,eAAO,MAAM,OAAO,EAAE,KAUrB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAgB/B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/ui",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"description": "Themeable React UI components for the WordPress Design System.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -44,15 +44,16 @@
 	"sideEffects": false,
 	"dependencies": {
 		"@base-ui/react": "^1.4.1",
-		"@wordpress/a11y": "^4.45.0",
-		"@wordpress/compose": "^7.45.0",
-		"@wordpress/element": "^6.45.0",
-		"@wordpress/i18n": "^6.18.0",
-		"@wordpress/icons": "^13.0.0",
-		"@wordpress/keycodes": "^4.45.0",
-		"@wordpress/primitives": "^4.45.0",
-		"@wordpress/private-apis": "^1.45.0",
-		"@wordpress/theme": "^0.12.0",
+		"@wordpress/a11y": "^4.46.0",
+		"@wordpress/compose": "^7.46.0",
+		"@wordpress/element": "^6.46.0",
+		"@wordpress/i18n": "^6.19.0",
+		"@wordpress/icons": "^13.1.0",
+		"@wordpress/keycodes": "^4.46.0",
+		"@wordpress/primitives": "^4.46.0",
+		"@wordpress/private-apis": "^1.46.0",
+		"@wordpress/style-runtime": "^0.2.0",
+		"@wordpress/theme": "^0.13.0",
 		"clsx": "^2.1.1",
 		"tabbable": "^6.4.0"
 	},
@@ -61,7 +62,7 @@
 		"@storybook/react-vite": "^10.2.8",
 		"@testing-library/jest-dom": "^6.9.1",
 		"@types/jest": "^29.5.14",
-		"@types/node": "^20.17.10",
+		"@types/node": "^20.19.39",
 		"storybook": "^10.2.8"
 	},
 	"peerDependencies": {
@@ -71,5 +72,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "8c229eaed0e88c9827e2da3d73a78f9ddd77714b"
+	"gitHead": "51264e33b95fadff9a06b68141e674ce9cde9675"
 }

package/src/alert-dialog/popup.tsx

@@ -8,7 +8,7 @@ import {
 	privateApis as themePrivateApis,
 } from '@wordpress/theme';
 
-import { renderPortalWithChildren } from '../utils/render-portal-with-children';
+import { renderSlotWithChildren } from '../utils/render-slot-with-children';
 import { Button } from '../button';
 import dialogStyles from '../dialog/style.module.css';
 import focusStyles from '../utils/css/focus.module.css';
@@ -178,7 +178,7 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 			</>
 		);
 
-		return renderPortalWithChildren( portal, <Portal />, portalChildren );
+		return renderSlotWithChildren( portal, <Portal />, portalChildren );
 	}
 );
 

package/src/alert-dialog/stories/index.story.tsx

@@ -12,12 +12,20 @@ const meta: Meta< typeof AlertDialog.Root > = {
 	component: AlertDialog.Root,
 	subcomponents: {
 		'AlertDialog.Trigger': AlertDialog.Trigger,
+		'AlertDialog.Portal': AlertDialog.Portal,
 		'AlertDialog.Popup': AlertDialog.Popup,
 	},
 	argTypes: {
 		onConfirm: { action: fn() },
 		onOpenChange: { action: fn() },
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of overlays compatibility. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

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

@@ -6,6 +6,12 @@ const meta: Meta< typeof Badge > = {
 	tags: [ 'manifest' ],
 	title: 'Design System/Components/Badge',
 	component: Badge,
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 

package/src/button/button.tsx

@@ -9,6 +9,9 @@ import resetStyles from '../utils/css/resets.module.css';
 import focusStyles from '../utils/css/focus.module.css';
 import defenseStyles from '../utils/css/global-css-defense.module.css';
 
+/**
+ * A versatile button component with multiple variants, tones, and sizes.
+ */
 export const Button = forwardRef< HTMLButtonElement, ButtonProps >(
 	function Button(
 		{

package/src/button/icon.tsx

@@ -1,14 +1,7 @@
 import { forwardRef } from '@wordpress/element';
-import { type IconProps } from '../icon/types';
+import { type ButtonIconProps } from './types';
 import { Icon } from '../icon';
 
-interface ButtonIconProps extends IconProps {
-	/**
-	 * The icon to display, from the `@wordpress/icons` package.
-	 */
-	icon: IconProps[ 'icon' ];
-}
-
 export const ButtonIcon = forwardRef< SVGSVGElement, ButtonIconProps >(
 	function ButtonIcon( { icon, ...props }, ref ) {
 		return (

package/src/button/index.ts

@@ -1,16 +1,15 @@
-import { Button as ButtonButton } from './button';
+import { Button as _Button } from './button';
 import { ButtonIcon } from './icon';
 
+ButtonIcon.displayName = 'Button.Icon';
+
 /**
  * A versatile button component with multiple variants, tones, and sizes.
- * Built on design tokens for consistent theming and accessibility.
  */
-export const Button = Object.assign( ButtonButton, {
+export const Button = Object.assign( _Button, {
 	/**
 	 * An icon component specifically designed to work well when rendered inside
 	 * a `Button` component.
 	 */
 	Icon: ButtonIcon,
-} ) as typeof ButtonButton & {
-	Icon: typeof ButtonIcon;
-};
+} );

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

@@ -6,11 +6,21 @@ import { Button } from '../index';
 const meta: Meta< typeof Button > = {
 	title: 'Design System/Components/Button',
 	component: Button,
+	subcomponents: {
+		'Button.Icon': Button.Icon,
+	},
 	argTypes: {
 		'aria-pressed': {
 			control: { type: 'boolean' },
 		},
 	},
+	parameters: {
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components` and text overflow behavior. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',
+		},
+	},
 };
 export default meta;
 

package/src/button/types.ts

@@ -1,5 +1,6 @@
 import { type ReactNode, type HTMLAttributes } from 'react';
 import type { Button as _Button } from '@base-ui/react/button';
+import { type IconProps } from '../icon/types';
 import type { ComponentProps } from '../utils/types';
 
 type _ButtonProps = ComponentProps< typeof _Button >;
@@ -70,3 +71,10 @@ export interface ButtonProps
 	 */
 	loadingAnnouncement?: string;
 }
+
+export interface ButtonIconProps extends IconProps {
+	/**
+	 * The icon to display, from the `@wordpress/icons` package.
+	 */
+	icon: IconProps[ 'icon' ];
+}

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

@@ -33,6 +33,12 @@ const meta: Meta< typeof Card.Root > = {
 		'Card.FullBleed': Card.FullBleed,
 		'Card.Title': Card.Title,
 	},
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 

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

@@ -10,6 +10,12 @@ const meta: Meta< typeof Collapsible.Root > = {
 		'Collapsible.Trigger': Collapsible.Trigger,
 		'Collapsible.Panel': Collapsible.Panel,
 	},
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 

package/src/collapsible-card/header.tsx

@@ -1,3 +1,4 @@
+import { mergeProps, useRender } from '@base-ui/react';
 import clsx from 'clsx';
 import { forwardRef, useMemo, useState } from '@wordpress/element';
 import { chevronDown } from '@wordpress/icons';
@@ -15,6 +16,12 @@ import type { HeaderProps } from './types';
  * toggle trigger — clicking anywhere on it expands or collapses the
  * card's content.
  *
+ * 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.
@@ -31,48 +38,54 @@ export const Header = forwardRef< HTMLDivElement, HeaderProps >(
 			[ setDescriptionId ]
 		);
 
-		return (
-			<HeaderDescriptionIdContext.Provider value={ contextValue }>
-				<Collapsible.Trigger
-					className={ clsx( styles.header, className ) }
-					render={
-						<Card.Header
-							ref={ ref }
-							render={ render }
-							{ ...restProps }
-						/>
-					}
-					nativeButton={ false }
-					aria-describedby={ descriptionId }
-				>
-					<div className={ styles[ 'header-content' ] }>
-						{ children }
-					</div>
-					<div
-						className={ clsx(
-							styles[ 'header-trigger-positioner' ]
-						) }
-					>
-						<div
-							className={ clsx(
-								styles[ 'header-trigger-wrapper' ],
-								defenseStyles.div,
-								// While the interactive trigger element is the whole header,
-								// the focus ring will be displayed only on the icon to visually
-								// emulate it being the button.
-								focusStyles[
-									'outset-ring--focus-parent-visible'
-								]
-							) }
+		return useRender( {
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: mergeProps< 'div' >( restProps, {
+				className: clsx(
+					defenseStyles.heading,
+					styles[ 'heading-wrapper' ],
+					className
+				),
+				children: (
+					<HeaderDescriptionIdContext.Provider value={ contextValue }>
+						<Collapsible.Trigger
+							className={ styles.header }
+							render={ <Card.Header /> }
+							nativeButton={ false }
+							aria-describedby={ descriptionId }
 						>
-							<Icon
-								icon={ chevronDown }
-								className={ styles[ 'header-trigger' ] }
-							/>
-						</div>
-					</div>
-				</Collapsible.Trigger>
-			</HeaderDescriptionIdContext.Provider>
-		);
+							<div className={ styles[ 'header-content' ] }>
+								{ children }
+							</div>
+							<div
+								className={ clsx(
+									styles[ 'header-trigger-positioner' ]
+								) }
+							>
+								<div
+									className={ clsx(
+										styles[ 'header-trigger-wrapper' ],
+										defenseStyles.div,
+										// While the interactive trigger element is the whole header,
+										// the focus ring will be displayed only on the icon to visually
+										// emulate it being the button.
+										focusStyles[
+											'outset-ring--focus-parent-visible'
+										]
+									) }
+								>
+									<Icon
+										icon={ chevronDown }
+										className={ styles[ 'header-trigger' ] }
+									/>
+								</div>
+							</div>
+						</Collapsible.Trigger>
+					</HeaderDescriptionIdContext.Provider>
+				),
+			} ),
+		} );
 	}
 );

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

@@ -34,6 +34,12 @@ const meta: Meta< typeof CollapsibleCard.Root > = {
 		'CollapsibleCard.HeaderDescription': CollapsibleCard.HeaderDescription,
 		'CollapsibleCard.Content': CollapsibleCard.Content,
 	},
+	parameters: {
+		componentStatus: {
+			status: 'recommended',
+			whereUsed: 'global',
+		},
+	},
 };
 export default meta;
 
@@ -159,6 +165,61 @@ export const Stacked: Story = {
 	),
 };
 
+/**
+ * `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 } },
+	render: () => (
+		<div
+			style={ {
+				display: 'flex',
+				flexDirection: 'column',
+				gap: 'var(--wpds-dimension-gap-lg)',
+			} }
+		>
+			<CollapsibleCard.Root>
+				<CollapsibleCard.Header render={ <h2 /> }>
+					<Card.Title>Heading level 2</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>
+						The wrapper renders as an h2 element when the consumer
+						passes an h2 React element to the render prop.
+					</Text>
+				</CollapsibleCard.Content>
+			</CollapsibleCard.Root>
+			<CollapsibleCard.Root>
+				<CollapsibleCard.Header render={ <h3 /> }>
+					<Card.Title>Heading level 3</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>
+						Pass any of h1–h6 to choose the level that fits the
+						surrounding document outline.
+					</Text>
+				</CollapsibleCard.Content>
+			</CollapsibleCard.Root>
+			<CollapsibleCard.Root>
+				<CollapsibleCard.Header>
+					<Card.Title>No heading (default)</Card.Title>
+				</CollapsibleCard.Header>
+				<CollapsibleCard.Content>
+					<Text>
+						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>
+		</div>
+	),
+};
+
 /**
  * A collapsible card with a `HeaderDescription` that provides supplementary
  * information (e.g. status, summary) as an `aria-describedby` relationship.

package/src/collapsible-card/style.module.css

@@ -1,6 +1,26 @@
 @layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
 
 @layer wp-ui-components {
+	/*
+	 * 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;
+		--_gcd-heading-font-size: inherit;
+		--_gcd-heading-font-weight: inherit;
+		--_gcd-heading-margin: 0;
+
+		/* Properties not covered by the defense file. */
+		font-family: inherit;
+		line-height: inherit;
+	}
+
 	.header-content {
 		flex: 1;
 		min-width: 0;

package/src/collapsible-card/test/index.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, within } from '@testing-library/react';
 import { userEvent } from '@testing-library/user-event';
 import { createRef } from '@wordpress/element';
 import * as Card from '../../card';
@@ -179,6 +179,65 @@ describe( 'CollapsibleCard', () => {
 		} );
 	} );
 
+	describe( 'header wrapper', () => {
+		it( 'does not contribute a heading to the document outline by default', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header>
+						<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( 'wraps the trigger in a heading via `render`', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header render={ <h2 /> }>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			const heading = screen.getByRole( 'heading', {
+				level: 2,
+				name: 'Title',
+			} );
+			expect( heading ).toBeVisible();
+			expect(
+				within( heading ).getByRole( 'button', { name: 'Title' } )
+			).toBeVisible();
+		} );
+
+		it( 'forwards `className` and other props to the outer wrapper', () => {
+			render(
+				<CollapsibleCard.Root>
+					<CollapsibleCard.Header
+						className="custom-header"
+						data-testid="header"
+					>
+						<Card.Title>Title</Card.Title>
+					</CollapsibleCard.Header>
+				</CollapsibleCard.Root>
+			);
+
+			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' );
+		} );
+	} );
+
 	describe( 'HeaderDescription', () => {
 		it( 'sets aria-describedby on the trigger pointing to the description', () => {
 			render(

package/src/dialog/popup.tsx

@@ -9,7 +9,7 @@ import {
 import { unlock } from '../lock-unlock';
 import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
 import { SCROLL_CONTAINER_ATTR } from '../utils/use-overlay-scroll-state-attributes';
-import { renderPortalWithChildren } from '../utils/render-portal-with-children';
+import { renderSlotWithChildren } from '../utils/render-slot-with-children';
 import { DialogValidationProvider, useDialogModal } from './context';
 import { Portal } from './portal';
 import styles from './style.module.css';
@@ -24,8 +24,7 @@ const CLOSE_ICON_ATTR = 'data-wp-ui-dialog-close-icon';
  * Renders the dialog popup element that contains the dialog content.
  * Uses a portal to render outside the DOM hierarchy.
  *
- * When `portal` is omitted, defaults to `Dialog.Portal`. Portal merging is
- * handled by `renderPortalWithChildren` (shared with other overlay `Popup`s).
+ * When `portal` is omitted, defaults to `Dialog.Portal`.
  */
 const Popup = forwardRef< HTMLDivElement, PopupProps >( function DialogPopup(
 	{
@@ -80,7 +79,7 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >( function DialogPopup(
 		</>
 	);
 
-	return renderPortalWithChildren( portal, <Portal />, portalChildren );
+	return renderSlotWithChildren( portal, <Portal />, portalChildren );
 } );
 
 export { Popup };