@wordpress/ui 0.11.1-next.v.202604091042.0 → 0.12.0

package/CHANGELOG.md

@@ -2,7 +2,52 @@
 
 ## Unreleased
 
-## 0.11.0-next.0 (2026-04-09)
+## 0.12.0 (2026-04-29)
+
+### Breaking Changes
+
+-   `Dialog`, `AlertDialog`, `Popover`, `Tooltip`, `Select`: **`Popup` portal API** ([#77452](https://github.com/WordPress/gutenberg/pull/77452)). Add `Portal` subcomponents and an optional `portal` prop on `Popup` (when omitted, the default `Portal` is used). Remove `container` from every `Popup` and `portalClassName` from `Dialog.Popup` / `AlertDialog.Popup`; pass `portal={ <Matching.Portal … /> }` for `container`, `className`, `style`, and other portal options.
+-   `Popover`, `Tooltip`, `Select`: `style` and `className` on `Popup` are now forwarded to the inner Base UI `Popup` element instead of the outer `Positioner`. To override the per-instance z-index, pass `portal={ <Overlay.Portal style={ { '--wp-ui-<overlay>-z-index': '9999' } } /> }` (or set the variable globally on a wrapping element); inline `style={ { zIndex: … } }` on `Popup` no longer reaches the positioned element.
+-   `Dialog`, `Drawer`: Scrolling now requires the new `Dialog.Content` / `Drawer.Content` subcomponent; the popup itself no longer scrolls. Rendering `Header` / `Footer` as siblings of `Content` pins them to the popup edges; nesting them inside `Content` opts out of pinning. `AlertDialog.Popup` adds `stickyHeader` / `stickyFooter` props (default `true`) for the same choice on its internal chrome ([#77559](https://github.com/WordPress/gutenberg/pull/77559)).
+
+### New Features
+
+-   Add `Drawer` primitive ([#76690](https://github.com/WordPress/gutenberg/pull/76690)).
+-   Add `Autocomplete` primitive ([#77642](https://github.com/WordPress/gutenberg/pull/77642)).
+
+### Documentation
+
+-   Restructure setup docs into "Within standard WordPress editor screens" and "Elsewhere" for clarity ([#77338](https://github.com/WordPress/gutenberg/pull/77338)).
+
+### Bug Fixes
+
+-   `Link`: Fix text decoration on the `unstyled` variant when `openInNewTab` is enabled, and simplify new-tab icon markup ([#77420](https://github.com/WordPress/gutenberg/pull/77420)).
+-   `Dialog`, `AlertDialog`, `Popover`, `Tooltip`, `Select`: Restore focus-trap tabbability through `ThemeProvider`'s `display: contents` wrapper ([#77381](https://github.com/WordPress/gutenberg/pull/77381), [#77520](https://github.com/WordPress/gutenberg/pull/77520)).
+-   Remove the transitive peer dependency on `date-fns` / `@date-fns/tz` ([#77520](https://github.com/WordPress/gutenberg/pull/77520)), resolving [#77395](https://github.com/WordPress/gutenberg/issues/77395).
+-   `Text`: Apply both heading and paragraph CSS defenses regardless of variant, so the correct defense kicks in based on the rendered element rather than the typographic variant ([#77461](https://github.com/WordPress/gutenberg/pull/77461)).
+-   `CollapsibleCard`: Fix missing keyboard focus ring on the header chevron icon when rendered inside wp-admin ([#77468](https://github.com/WordPress/gutenberg/pull/77468)).
+-   `CollapsibleCard`: Prevent the focus ring of focusable descendants from being clipped by the panel's overflow once the panel is fully expanded ([#77667](https://github.com/WordPress/gutenberg/pull/77667)).
+-   `Tabs`: Fix missing keyboard focus ring on the panel in Windows High Contrast mode when rendered inside wp-admin ([#77469](https://github.com/WordPress/gutenberg/pull/77469)).
+
+### Enhancements
+
+-   `Dialog` / `AlertDialog` / `Drawer`: Pin header / footer chrome to the popup edges when the body overflows, and show separator borders only while there is off-screen content in that direction ([#77559](https://github.com/WordPress/gutenberg/pull/77559)).
+-   `Dialog`: Add `Dialog.Description` sub-component, expose `onOpenChangeComplete`, skip the backdrop when `modal` is not `true`, use `100dvh` for viewport-based heights so the popup fits the dynamic viewport on mobile, and forward `className` on `Dialog.Title` ([#77194](https://github.com/WordPress/gutenberg/pull/77194)).
+-   `Dialog`: `Dialog.Header` and `Dialog.Footer` now default to `<header>` and `<footer>` elements for richer landmark semantics. Their `ref` type widens from `HTMLDivElement` to `HTMLElement`; pass `render` to opt out of the default tag ([#76690](https://github.com/WordPress/gutenberg/pull/76690)).
+-   `Dialog`, `Popover`: Upgrade dev-only title validation from mount-only to cleanup-based re-validation, catching conditionally rendered titles ([#77165](https://github.com/WordPress/gutenberg/pull/77165)).
+-   `Link`: Honor `openInNewTab` consistently instead of treating hash links as a special case ([#77422](https://github.com/WordPress/gutenberg/pull/77422)).
+-   `Select`: Tighten spacing after checkmark when `Select.Item` is `size="small"` ([#77642](https://github.com/WordPress/gutenberg/pull/77642)).
+-   `Dialog`, `Drawer`, `Popover`: Align title and description colors across all three overlay primitives. Title color is now authored explicitly (resilient to global CSS defenses), and description color now inherits from the popup foreground token instead of overriding to the weak variant ([#77692](https://github.com/WordPress/gutenberg/pull/77692)).
+-   `Dialog`, `AlertDialog`, `Drawer`, `Popover`, `Select`, `Tooltip`: Unify the hairline border across overlay popups. Popups without a backdrop show a token-colored border in regular mode; popups with a backdrop hide the border (which would be redundant with the backdrop's containment); all popups show a `CanvasText` border in forced-colors mode ([#77691](https://github.com/WordPress/gutenberg/pull/77691)).
+-   `Link`: Use `text-decoration-thickness: from-font` so the underline honors the font's metrics, instead of a fixed sub-pixel value that renders inconsistently across device pixel ratios ([#77790](https://github.com/WordPress/gutenberg/pull/77790)).
+
+### Internal
+
+-   Update `@base-ui/react` from `1.4.0` to [`1.4.1`](https://github.com/mui/base-ui/releases/tag/v1.4.1) ([#77520](https://github.com/WordPress/gutenberg/pull/77520)).
+-   Extract shared `useScheduleValidation` hook; refactor `Dialog`, `Popover`, and `Tabs` validation contexts to use it ([#77165](https://github.com/WordPress/gutenberg/pull/77165)).
+-   `Tabs`: Wrap two validation timeout waits in `act(...)` to avoid intermittent test warnings ([#77319](https://github.com/WordPress/gutenberg/pull/77319)).
+
+## 0.11.0 (2026-04-15)
 
 ### Breaking Changes
 
@@ -19,15 +64,27 @@
 
 ### Bug Fixes
 
+-   `Card.Title`, `EmptyState.Title`, `EmptyState.Description`: Fix ref and props being lost when a custom `render` element is provided ([#77160](https://github.com/WordPress/gutenberg/pull/77160)).
+-   `Tabs.List`: Fix `render` prop being silently discarded ([#77160](https://github.com/WordPress/gutenberg/pull/77160)).
 -   `Card`: Set default foreground color on `Card.Root` so content and `currentColor` icons (for example the `CollapsibleCard` chevron) are themeable by default ([#77013](https://github.com/WordPress/gutenberg/pull/77013)).
 
 ### Enhancements
 
+-   `Dialog`: Update `Header` layout to support multiple trailing elements alongside the title ([#77161](https://github.com/WordPress/gutenberg/pull/77161), [#77334](https://github.com/WordPress/gutenberg/pull/77334)).
+-   `Dialog`: Use `Text` internally for `Dialog.Title`, adopting the `heading-xl` variant for consistent typography ([#77161](https://github.com/WordPress/gutenberg/pull/77161)).
+-   `Dialog`, `AlertDialog`, `Tooltip`, `Select`: Add `container` prop to `Popup` for custom portal targets ([#77163](https://github.com/WordPress/gutenberg/pull/77163)).
 -   Add defensive styles against global WordPress stylesheets like common.css and forms.css ([#76783](https://github.com/WordPress/gutenberg/pull/76783)).
+-   `VisuallyHidden`: Improve Storybook stories and documentation for the `render` prop composition pattern.
 
 ### Internal
 
+-   `Card`: Remove redundant `margin: 0` from `Card.Title` now that `Text` applies it by default ([#77187](https://github.com/WordPress/gutenberg/pull/77187)).
+-   Normalize `render` prop handling across components and document conventions in `CONTRIBUTING.md` ([#77160](https://github.com/WordPress/gutenberg/pull/77160)).
 -   `AlertDialog`: Rewrite internals to use Base UI's `AlertDialog` primitives directly instead of `Dialog` wrappers. Introduces an internal state machine for async confirm flows ([#76937](https://github.com/WordPress/gutenberg/pull/76937)).
+-   `Field.Label`, `Fieldset.Legend`, `Field.Details`: Refactor `VisuallyHidden` composition to preserve semantic HTML elements when visually hiding content.
+-   `Badge`: Use `Text` component for typography ([#77295](https://github.com/WordPress/gutenberg/pull/77295)).
+-   `Notice.ActionLink`: Use `Text` component for typography ([#77332](https://github.com/WordPress/gutenberg/pull/77332)).
+-   Update `@base-ui/react` from `1.3.0` to `1.4.0` ([#77308](https://github.com/WordPress/gutenberg/pull/77308)).
 
 ## 0.10.0 (2026-04-01)
 

package/CONTRIBUTING.md

@@ -57,6 +57,130 @@ Why?
 -   `.Root` has required subparts, signalling an expectation that it must be composed
     -   A non-root component can still have _optional_ sub-parts, like a `Button.Icon`
 
+## `render` Prop and Ref Forwarding
+
+All `@wordpress/ui` components support a `render` prop (via the `ComponentProps` utility type) that lets consumers swap the underlying HTML element. This section codifies the two canonical implementation patterns, the rules for handling `render`, and common anti-patterns to avoid.
+
+### Canonical Patterns
+
+The correct approach depends on whether the component wraps a Base UI primitive or renders its own element.
+
+#### Pattern A: Custom components — `useRender` + `mergeProps`
+
+For components that do **not** wrap a Base UI primitive, use `useRender` and `mergeProps` from `@base-ui/react`. Destructure `render` from props (required by the `useRender` API), and pass it together with `ref` and merged props:
+
+```tsx
+import { useRender, mergeProps } from '@base-ui/react';
+import { forwardRef } from '@wordpress/element';
+
+export const Root = forwardRef( function MyComponent( { render, className, ...restProps }, ref ) {
+    const element = useRender( {
+        render,
+        defaultTagName: 'div',
+        ref,
+        props: mergeProps( { className: styles.root }, restProps ),
+    } );
+
+    return element;
+} );
+```
+
+`useRender` handles element creation, ref composition, and prop merging.
+
+#### Pattern B: Wrapper components — pass `ref` explicitly, spread `...props`
+
+For components that wrap a Base UI primitive or another `@wordpress/ui` component, pass the forwarded `ref` explicitly and spread `...props` (which carries `render` through implicitly):
+
+```tsx
+import { Collapsible as _Collapsible } from '@base-ui/react/collapsible';
+import { forwardRef } from '@wordpress/element';
+
+export const Trigger = forwardRef( function MyTrigger( props, ref ) {
+    return <_Collapsible.Trigger ref={ ref } { ...props } />;
+} );
+```
+
+The inner component (Base UI or `@wordpress/ui`) handles `render` and ref composition internally.
+
+### Explicit vs Implicit `render` Handling
+
+**Prefer implicit handling (via `...props` rest spread) unless the component needs to interact with `render`.**
+
+"Interact" means one of:
+
+1. **Assign a default** — the component overrides the default element (e.g., `render = DEFAULT_TAG`).
+2. **Transform** — the component wraps or modifies the value before passing it.
+3. **Discard** — the component intentionally prevents element customization. In this case, destructure `render` to remove it from rest props, **and** `Omit` it from the type so consumers get a TypeScript error instead of silent no-op behavior.
+4. **Pass to `useRender`** — Pattern A components where the hook API requires it as a named argument.
+
+In all other cases, let `render` flow through `...props`. Destructuring `render` only to write `render={ render }` is ceremony with no behavioral effect.
+
+### Overriding the Default Element
+
+When a component needs to render a different element than its inner component's default (e.g., a `<div>` instead of `<span>`), hoist the default to a **module-level constant** and assign it as a destructuring default.
+
+The default can be a **JSX element** or a **render function**, depending on what the component needs:
+
+```tsx
+// JSX element — suitable when you only need to swap the tag.
+const DEFAULT_TAG = <div />;
+
+export const Title = forwardRef( function MyTitle(
+    { render = DEFAULT_TAG, className, children, ...props },
+    ref
+) {
+    return (
+        <Text ref={ ref } render={ render } className={ className } { ...props }>
+            { children }
+        </Text>
+    );
+} );
+```
+
+```tsx
+// Render function — useful when the default needs to compose
+// other components or add additional props.
+const DEFAULT_RENDER = ( props: React.ComponentProps< typeof Stack > ) => (
+    <Stack { ...props } direction="column" gap="sm" />
+);
+
+export const Root = forwardRef( function MyRoot(
+    { className, render = DEFAULT_RENDER, ...restProps },
+    ref
+) {
+    return (
+        <_Field.Root ref={ ref } className={ className } render={ render } { ...restProps } />
+    );
+} );
+```
+
+When using a JSX element, React elements are immutable descriptors — `useRender` calls `cloneElement` on them (creating a new element), never mutating the original. In both cases, a hoisted constant avoids allocating a fresh object every render and gives React/Base UI a stable reference for equality checks.
+
+### Anti-patterns
+
+#### Bundling `ref` and `props` into a render fallback
+
+```tsx
+// BAD: ref and props are lost when consumer provides render
+render={ render ?? <div ref={ ref } { ...props } /> }
+```
+
+When `render` is provided by the consumer, `ref` and `...props` remain on the unused fallback element and never reach the actual rendered element. Always pass `ref` and `...props` separately to the inner component.
+
+#### Unnecessary explicit destructure
+
+```tsx
+// BAD: destructure-and-pass-through with no interaction
+function MyComponent( { render, ...props }, ref ) {
+    return <Inner ref={ ref } render={ render } { ...props } />;
+}
+
+// GOOD: let render flow through ...props
+function MyComponent( props, ref ) {
+    return <Inner ref={ ref } { ...props } />;
+}
+```
+
 ## CSS Architecture
 
 ### CSS Layers

package/README.md

@@ -28,13 +28,13 @@ npm install @wordpress/ui
 
 As an implementation of the design system and companion to the `@wordpress/theme` package, these components depend on CSS custom properties defined by the theme package. What you need to set up depends on whether you're building for a WordPress context, and how much of the theming features you want to use.
 
-### Within WordPress
+### Within standard WordPress editor screens
 
-Stylesheets are managed on your behalf in a WordPress context, so you don't need to worry about loading them yourself.
+In standard WordPress editor screens (such as the post editor or the site editor), stylesheets, isolation styles, and layout styles are managed centrally by Gutenberg. You don't need to add any setup yourself — and you should avoid doing so in this shared context to prevent conflicts.
 
-### Outside WordPress
+### Elsewhere
 
-While the components ship with basic fallbacks for every CSS custom property, it's recommended that you install and load the design tokens stylesheet to support the full range of theming capabilities:
+The components ship with built-in fallback values for all CSS custom properties, so they work out of the box without any theme setup. For full theming capabilities, it's recommended that you install and load the design tokens stylesheet:
 
 ```
 npm install @wordpress/theme
@@ -50,7 +50,15 @@ Also, to ensure that portaled popovers appear correctly, add these isolation sty
 
 ```css
 .root {
-  isolation: isolate;
+	isolation: isolate;
+}
+```
+
+Finally, in order to support overlay elements such as backdrops to correctly cover the whole browser viewport even when scrolled, add the following style to your global styles:
+
+```css
+body {
+	position: relative;
 }
 ```
 
@@ -124,10 +132,10 @@ Interactive components that manage internal state (such as open/closed, selected
 
 For a given state `x`, the convention is:
 
-| Prop | Purpose |
-| --- | --- |
-| `defaultX` | Sets the initial value in **uncontrolled** mode. The component manages subsequent state changes internally. |
-| `x` | Sets the current value in **controlled** mode. The consumer is responsible for updating the value in response to changes. |
+| Prop        | Purpose                                                                                                                                 |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultX`  | Sets the initial value in **uncontrolled** mode. The component manages subsequent state changes internally.                             |
+| `x`         | Sets the current value in **controlled** mode. The consumer is responsible for updating the value in response to changes.               |
 | `onXChange` | Callback invoked when the state changes. Receives the new value as its first argument. Works in both controlled and uncontrolled modes. |
 
 For example, a component with an open/closed state would expose:

package/build/alert-dialog/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var alert_dialog_exports = {};
 __export(alert_dialog_exports, {
   Popup: () => import_popup.Popup,
+  Portal: () => import_portal.Portal,
   Root: () => import_root.Root,
   Trigger: () => import_trigger.Trigger
 });
@@ -28,9 +29,11 @@ module.exports = __toCommonJS(alert_dialog_exports);
 var import_root = require("./root.cjs");
 var import_trigger = require("./trigger.cjs");
 var import_popup = require("./popup.cjs");
+var import_portal = require("./portal.cjs");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Popup,
+  Portal,
   Root,
   Trigger
 });

package/build/alert-dialog/index.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/alert-dialog/index.ts"],
-  "sourcesContent": ["export { Root } from './root';\nexport { Trigger } from './trigger';\nexport { Popup } from './popup';\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAAqB;AACrB,qBAAwB;AACxB,mBAAsB;",
+  "sourcesContent": ["export { Root } from './root';\nexport { Trigger } from './trigger';\nexport { Popup } from './popup';\nexport { Portal } from './portal';\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAAqB;AACrB,qBAAwB;AACxB,mBAAsB;AACtB,oBAAuB;",
   "names": []
 }

package/build/alert-dialog/popup.cjs

@@ -36,33 +36,56 @@ module.exports = __toCommonJS(popup_exports);
 var import_alert_dialog = require("@base-ui/react/alert-dialog");
 var import_clsx = __toESM(require("clsx"));
 var import_element = require("@wordpress/element");
+var import_compose = require("@wordpress/compose");
 var import_i18n = require("@wordpress/i18n");
 var import_theme = require("@wordpress/theme");
+var import_render_portal_with_children = require("../utils/render-portal-with-children.cjs");
 var import_button = require("../button/index.cjs");
 
 // packages/ui/src/dialog/style.module.css
-if (typeof document !== "undefined" && process.env.NODE_ENV !== "test" && !document.head.querySelector("style[data-wp-hash='6520ba3376']")) {
+if (typeof document !== "undefined" && process.env.NODE_ENV !== "test" && !document.head.querySelector("style[data-wp-hash='42f1988e07']")) {
   const style = document.createElement("style");
-  style.setAttribute("data-wp-hash", "6520ba3376");
-  style.appendChild(document.createTextNode('@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;@layer wp-ui-components{._074affe4c56b4f2f__backdrop{background-color:#00000059;inset:0;position:fixed;z-index:var(--wp-ui-dialog-z-index,initial);&[data-ending-style],&[data-starting-style]{opacity:0}&[data-open]{opacity:1}@media not (prefers-reduced-motion){transition:opacity .2s ease-out}}._8acaa98861620d4d__popup{background-color:var(--wpds-color-bg-surface-neutral-strong,#fff);border-radius:var(--wpds-border-radius-lg,8px);box-shadow:var(--wpds-elevation-lg,0 5px 15px 0 #00000014,0 15px 27px 0 #00000012,0 30px 36px 0 #0000000a,0 50px 43px 0 #00000005);box-sizing:border-box;color:var(--wpds-color-fg-content-neutral,#1e1e1e);font-family:var(--wpds-font-family-body,-apple-system,system-ui,"Segoe UI","Roboto","Oxygen-Sans","Ubuntu","Cantarell","Helvetica Neue",sans-serif);font-size:var(--wpds-font-size-md,13px);left:50%;line-height:var(--wpds-font-line-height-md,24px);max-height:calc(100vh - var(--wpds-dimension-padding-2xl, 24px)*2);min-width:var(--wpds-dimension-surface-width-sm,320px);overflow:auto;padding:var(--wpds-dimension-padding-2xl,24px);position:fixed;top:50%;transform:translate(-50%,-50%);width:calc(100vw - var(--wpds-dimension-padding-2xl, 24px)*2);z-index:var(--wp-ui-dialog-z-index,initial);&[data-ending-style],&[data-starting-style]{opacity:0;transform:translate(-50%,-50%) scale(.9)}@media not (prefers-reduced-motion){transition:opacity .2s cubic-bezier(1,0,.2,1),transform .2s cubic-bezier(1,0,.2,1);&[data-open]{transition:opacity .2s cubic-bezier(.29,0,0,1),transform .2s cubic-bezier(.29,0,0,1)}}@media (min-width:480px){min-width:var(--wpds-dimension-surface-width-md,400px)}&._7acfa67ebf092988__is-small{max-width:var(--wpds-dimension-surface-width-md,400px)}&._1eeeed880cb5769d__is-medium{max-width:var(--wpds-dimension-surface-width-lg,560px)}&._99f900b2267e22d0__is-large{max-width:var(--wpds-dimension-surface-width-2xl,960px)}&.b49f7ff9c06fe387__is-stretch{max-width:none}&.dcd4c2f5036cbf1a__is-full{height:100vh}}._76fb3b28fcbd45fc__header{align-items:center;display:flex;justify-content:space-between;margin-bottom:var(--wpds-dimension-gap-lg,16px)}.f636832002af749e__title{color:var(--wpds-color-fg-content-neutral,#1e1e1e);font-size:var(--wpds-font-size-xl,20px);font-weight:var(--wpds-font-weight-medium,499);line-height:var(--wpds-font-line-height-xl,32px);margin:0}._00eeb4f220cddae3__footer{align-items:center;display:flex;gap:var(--wpds-dimension-gap-sm,8px);justify-content:flex-end;margin-top:var(--wpds-dimension-gap-lg,16px);padding-top:var(--wpds-dimension-padding-lg,16px)}}'));
+  style.setAttribute("data-wp-hash", "42f1988e07");
+  style.appendChild(document.createTextNode('@layer wp-ui-components{.f1c50237c4787636__header{min-height:32px;padding-block:var(--wpds-dimension-padding-2xl,24px) var(--wpds-dimension-gap-lg,16px)}._579f95efdec92a66__footer,.f1c50237c4787636__header{align-items:center;display:flex;gap:var(--wpds-dimension-gap-sm,8px);padding-inline:var(--wpds-dimension-padding-2xl,24px)}._579f95efdec92a66__footer{justify-content:flex-end;padding-block:var(--wpds-dimension-gap-lg,16px) var(--wpds-dimension-padding-2xl,24px)}._5371cc08aad82574__title{--_gcd-heading-color:var(--wpds-color-fg-content-neutral,#1e1e1e);--_gcd-heading-margin:0 auto 0 0;color:var(--wpds-color-fg-content-neutral,#1e1e1e);margin-inline-end:auto;&:dir(rtl){--_gcd-heading-margin:0 0 0 auto}}._766d9011d37ce2d9__content{flex:1 1 auto;min-block-size:0;overflow-block:auto;overflow-inline:hidden;padding:var(--wpds-dimension-padding-2xl,24px);&:focus-visible{outline-offset:calc(var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px))*-1)}}.f1c50237c4787636__header:has(~._766d9011d37ce2d9__content){border-block-end:1px solid #0000;padding-block-end:calc(var(--wpds-dimension-gap-lg, 16px) - 1px)}.f1c50237c4787636__header~._766d9011d37ce2d9__content{padding-block-start:0}._766d9011d37ce2d9__content~._579f95efdec92a66__footer{border-block-start:1px solid #0000;padding-block-start:calc(var(--wpds-dimension-gap-lg, 16px) - 1px)}._766d9011d37ce2d9__content:has(~._579f95efdec92a66__footer){padding-block-end:0}._766d9011d37ce2d9__content>.f1c50237c4787636__header{padding-inline:0}._766d9011d37ce2d9__content>.f1c50237c4787636__header:first-child{padding-block-start:0}._766d9011d37ce2d9__content>._579f95efdec92a66__footer{padding-inline:0}._766d9011d37ce2d9__content>._579f95efdec92a66__footer:last-child{padding-block-end:0}.f1c50237c4787636__header:has(~[data-wp-ui-overlay-scroll-container][data-wp-ui-overlay-scrolled-from-top]){border-block-end-color:var(--wpds-color-stroke-surface-neutral,#dbdbdb)}[data-wp-ui-overlay-scroll-container][data-wp-ui-overlay-scrolled-from-bottom]~._579f95efdec92a66__footer{border-block-start-color:var(--wpds-color-stroke-surface-neutral,#dbdbdb)}[data-wp-ui-overlay-modal] [data-wp-ui-overlay-scroll-container]{overscroll-behavior:contain}}@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;@layer wp-ui-components{._074affe4c56b4f2f__backdrop{background-color:#00000059;inset:0;position:fixed;z-index:var(--wp-ui-dialog-z-index,initial);&[data-ending-style],&[data-starting-style]{opacity:0}&[data-open]{opacity:1}@media not (prefers-reduced-motion){transition:opacity .2s ease-out}}._8acaa98861620d4d__popup{--viewport-inset:var(--wpds-dimension-padding-2xl,24px);background-color:var(--wpds-color-bg-surface-neutral-strong,#fff);border:var(--wpds-border-width-xs,1px) solid var(--wpds-color-stroke-surface-neutral,#dbdbdb);border-radius:var(--wpds-border-radius-lg,8px);box-shadow:var(--wpds-elevation-lg,0 5px 15px 0 #00000014,0 15px 27px 0 #00000012,0 30px 36px 0 #0000000a,0 50px 43px 0 #00000005);box-sizing:border-box;color:var(--wpds-color-fg-content-neutral,#1e1e1e);display:flex;flex-direction:column;font-family:var(--wpds-typography-font-family-body,-apple-system,system-ui,"Segoe UI","Roboto","Oxygen-Sans","Ubuntu","Cantarell","Helvetica Neue",sans-serif);font-size:var(--wpds-typography-font-size-md,13px);left:50%;line-height:var(--wpds-typography-line-height-md,24px);max-height:calc(100dvh - var(--viewport-inset)*2);min-width:var(--wpds-dimension-surface-width-sm,320px);overflow:hidden;position:fixed;top:50%;transform:translate(-50%,-50%);width:calc(100vw - var(--viewport-inset)*2);z-index:var(--wp-ui-dialog-z-index,initial);&[data-ending-style],&[data-starting-style]{opacity:0;transform:translate(-50%,-50%) scale(.9)}@media not (prefers-reduced-motion){transition:opacity .2s cubic-bezier(1,0,.2,1),transform .2s cubic-bezier(1,0,.2,1);&[data-open]{transition:opacity .2s cubic-bezier(.29,0,0,1),transform .2s cubic-bezier(.29,0,0,1)}}@media (min-width:480px){min-width:var(--wpds-dimension-surface-width-md,400px)}&._7acfa67ebf092988__is-small{max-width:var(--wpds-dimension-surface-width-md,400px)}&._1eeeed880cb5769d__is-medium{max-width:var(--wpds-dimension-surface-width-lg,560px)}&._99f900b2267e22d0__is-large{max-width:var(--wpds-dimension-surface-width-2xl,960px)}&.b49f7ff9c06fe387__is-stretch{max-width:none}&.dcd4c2f5036cbf1a__is-full{height:100dvh}}._074affe4c56b4f2f__backdrop~* ._8acaa98861620d4d__popup{border-color:#0000}@media (forced-colors:active){._074affe4c56b4f2f__backdrop~* ._8acaa98861620d4d__popup,._8acaa98861620d4d__popup{border-color:CanvasText}}._76fb3b28fcbd45fc__header [data-wp-ui-dialog-close-icon]{margin-inline-start:auto}.d9d6da914ef0a77c__description{margin-bottom:var(--wpds-dimension-gap-lg,16px)}}'));
   document.head.appendChild(style);
 }
-var style_default = { "backdrop": "_074affe4c56b4f2f__backdrop", "popup": "_8acaa98861620d4d__popup", "is-small": "_7acfa67ebf092988__is-small", "is-medium": "_1eeeed880cb5769d__is-medium", "is-large": "_99f900b2267e22d0__is-large", "is-stretch": "b49f7ff9c06fe387__is-stretch", "is-full": "dcd4c2f5036cbf1a__is-full", "header": "_76fb3b28fcbd45fc__header", "title": "f636832002af749e__title", "footer": "_00eeb4f220cddae3__footer" };
+var style_default = { "backdrop": "_074affe4c56b4f2f__backdrop", "popup": "_8acaa98861620d4d__popup", "is-small": "_7acfa67ebf092988__is-small", "is-medium": "_1eeeed880cb5769d__is-medium", "is-large": "_99f900b2267e22d0__is-large", "is-stretch": "b49f7ff9c06fe387__is-stretch", "is-full": "dcd4c2f5036cbf1a__is-full", "header": "_76fb3b28fcbd45fc__header f1c50237c4787636__header", "footer": "_00eeb4f220cddae3__footer _579f95efdec92a66__footer", "title": "f636832002af749e__title _5371cc08aad82574__title", "content": "_101038da9af7162f__content _766d9011d37ce2d9__content", "description": "d9d6da914ef0a77c__description" };
+
+// packages/ui/src/utils/css/focus.module.css
+if (typeof document !== "undefined" && process.env.NODE_ENV !== "test" && !document.head.querySelector("style[data-wp-hash='2a5ab8f3a7']")) {
+  const style = document.createElement("style");
+  style.setAttribute("data-wp-hash", "2a5ab8f3a7");
+  style.appendChild(document.createTextNode("@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;@layer wp-ui-utilities{._08e8a2e44959f892__outset-ring--focus,._970d04df7376df67__outset-ring--focus-within-except-active,.c5cb3ee4bddaa8e4__outset-ring--focus-within-visible,.cd83dfc2126a0846__outset-ring--focus-within,.d0541bc9dd9dc7b6__outset-ring--focus-visible,.e25b2bdd7aa21721__outset-ring--focus-except-active,.ecadb9e080e2dfa5__outset-ring--focus-parent-visible{@media not (prefers-reduced-motion){--_gcd-a-transition:outline 0.1s ease-out;transition:outline .1s ease-out}outline:0 solid #0000;outline-offset:1px}._08e8a2e44959f892__outset-ring--focus:focus,._970d04df7376df67__outset-ring--focus-within-except-active:focus-within:not(:has(:active)),.c5cb3ee4bddaa8e4__outset-ring--focus-within-visible:focus-within:has(:focus-visible),.cd83dfc2126a0846__outset-ring--focus-within:focus-within,.d0541bc9dd9dc7b6__outset-ring--focus-visible:focus-visible,.e25b2bdd7aa21721__outset-ring--focus-except-active:focus:not(:active),:focus-visible .ecadb9e080e2dfa5__outset-ring--focus-parent-visible{--_gcd-a-outline:var(--wpds-border-width-focus,var(--wp-admin-border-width-focus,2px)) solid var(--wpds-color-stroke-focus-brand,var(--wp-admin-theme-color,#3858e9));--_gcd-div-outline:var(--wpds-border-width-focus,var(--wp-admin-border-width-focus,2px)) solid var(--wpds-color-stroke-focus-brand,var(--wp-admin-theme-color,#3858e9));outline:var(--wpds-border-width-focus,var(--wp-admin-border-width-focus,2px)) solid var(--wpds-color-stroke-focus-brand,var(--wp-admin-theme-color,#3858e9))}}"));
+  document.head.appendChild(style);
+}
+var focus_default = { "outset-ring--focus": "_08e8a2e44959f892__outset-ring--focus", "outset-ring--focus-except-active": "e25b2bdd7aa21721__outset-ring--focus-except-active", "outset-ring--focus-visible": "d0541bc9dd9dc7b6__outset-ring--focus-visible", "outset-ring--focus-within": "cd83dfc2126a0846__outset-ring--focus-within", "outset-ring--focus-within-except-active": "_970d04df7376df67__outset-ring--focus-within-except-active", "outset-ring--focus-within-visible": "c5cb3ee4bddaa8e4__outset-ring--focus-within-visible", "outset-ring--focus-parent-visible": "ecadb9e080e2dfa5__outset-ring--focus-parent-visible" };
+
+// packages/ui/src/utils/css/overlay-chrome.module.css
+if (typeof document !== "undefined" && process.env.NODE_ENV !== "test" && !document.head.querySelector("style[data-wp-hash='6e76dbcbd9']")) {
+  const style = document.createElement("style");
+  style.setAttribute("data-wp-hash", "6e76dbcbd9");
+  style.appendChild(document.createTextNode("@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;@layer wp-ui-components{.f1c50237c4787636__header{min-height:32px;padding-block:var(--wpds-dimension-padding-2xl,24px) var(--wpds-dimension-gap-lg,16px)}._579f95efdec92a66__footer,.f1c50237c4787636__header{align-items:center;display:flex;gap:var(--wpds-dimension-gap-sm,8px);padding-inline:var(--wpds-dimension-padding-2xl,24px)}._579f95efdec92a66__footer{justify-content:flex-end;padding-block:var(--wpds-dimension-gap-lg,16px) var(--wpds-dimension-padding-2xl,24px)}._5371cc08aad82574__title{--_gcd-heading-color:var(--wpds-color-fg-content-neutral,#1e1e1e);--_gcd-heading-margin:0 auto 0 0;color:var(--wpds-color-fg-content-neutral,#1e1e1e);margin-inline-end:auto;&:dir(rtl){--_gcd-heading-margin:0 0 0 auto}}._766d9011d37ce2d9__content{flex:1 1 auto;min-block-size:0;overflow-block:auto;overflow-inline:hidden;padding:var(--wpds-dimension-padding-2xl,24px);&:focus-visible{outline-offset:calc(var(--wpds-border-width-focus, var(--wp-admin-border-width-focus, 2px))*-1)}}.f1c50237c4787636__header:has(~._766d9011d37ce2d9__content){border-block-end:1px solid #0000;padding-block-end:calc(var(--wpds-dimension-gap-lg, 16px) - 1px)}.f1c50237c4787636__header~._766d9011d37ce2d9__content{padding-block-start:0}._766d9011d37ce2d9__content~._579f95efdec92a66__footer{border-block-start:1px solid #0000;padding-block-start:calc(var(--wpds-dimension-gap-lg, 16px) - 1px)}._766d9011d37ce2d9__content:has(~._579f95efdec92a66__footer){padding-block-end:0}._766d9011d37ce2d9__content>.f1c50237c4787636__header{padding-inline:0}._766d9011d37ce2d9__content>.f1c50237c4787636__header:first-child{padding-block-start:0}._766d9011d37ce2d9__content>._579f95efdec92a66__footer{padding-inline:0}._766d9011d37ce2d9__content>._579f95efdec92a66__footer:last-child{padding-block-end:0}.f1c50237c4787636__header:has(~[data-wp-ui-overlay-scroll-container][data-wp-ui-overlay-scrolled-from-top]){border-block-end-color:var(--wpds-color-stroke-surface-neutral,#dbdbdb)}[data-wp-ui-overlay-scroll-container][data-wp-ui-overlay-scrolled-from-bottom]~._579f95efdec92a66__footer{border-block-start-color:var(--wpds-color-stroke-surface-neutral,#dbdbdb)}[data-wp-ui-overlay-modal] [data-wp-ui-overlay-scroll-container]{overscroll-behavior:contain}}"));
+  document.head.appendChild(style);
+}
+var overlay_chrome_default = { "header": "f1c50237c4787636__header", "footer": "_579f95efdec92a66__footer", "title": "_5371cc08aad82574__title", "content": "_766d9011d37ce2d9__content" };
 
 // packages/ui/src/alert-dialog/popup.tsx
+var import_use_deprioritized_initial_focus = require("../utils/use-deprioritized-initial-focus.cjs");
+var import_use_overlay_scroll_state_attributes = require("../utils/use-overlay-scroll-state-attributes.cjs");
 var import_lock_unlock = require("../lock-unlock.cjs");
 var import_stack = require("../stack/index.cjs");
 var import_text = require("../text/index.cjs");
 var import_context = require("./context.cjs");
+var import_portal = require("./portal.cjs");
 
 // packages/ui/src/alert-dialog/style.module.css
-if (typeof document !== "undefined" && process.env.NODE_ENV !== "test" && !document.head.querySelector("style[data-wp-hash='113a8b8edd']")) {
+if (typeof document !== "undefined" && process.env.NODE_ENV !== "test" && !document.head.querySelector("style[data-wp-hash='ea48258a83']")) {
   const style = document.createElement("style");
-  style.setAttribute("data-wp-hash", "113a8b8edd");
-  style.appendChild(document.createTextNode("@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;@layer wp-ui-components{._837a6eb481252f50__header{margin-bottom:var(--wpds-dimension-gap-lg,16px)}.dbff6618234a2a93__error-message{align-self:flex-end;color:var(--wpds-color-fg-content-error,#470000)}}@layer wp-ui-compositions{._2ddc2fc9155a1dad__irreversible-action{--wp-ui-button-background-color:var(--wpds-color-bg-interactive-error-strong,#cc1818);--wp-ui-button-background-color-active:var(--wpds-color-bg-interactive-error-strong-active,#b90000);--wp-ui-button-foreground-color:var(--wpds-color-fg-interactive-error-strong,#f2efef);--wp-ui-button-foreground-color-active:var(--wpds-color-fg-interactive-error-strong-active,#f2efef)}}"));
+  style.setAttribute("data-wp-hash", "ea48258a83");
+  style.appendChild(document.createTextNode("@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;@layer wp-ui-components{.dbff6618234a2a93__error-message{align-self:flex-end;color:var(--wpds-color-fg-content-error,#470000)}._66cf5fe0c6a030bd__footer-column{align-items:stretch;flex-direction:column;gap:var(--wpds-dimension-gap-md,12px);justify-content:flex-start}}@layer wp-ui-compositions{._2ddc2fc9155a1dad__irreversible-action{--wp-ui-button-background-color:var(--wpds-color-bg-interactive-error-strong,#cc1818);--wp-ui-button-background-color-active:var(--wpds-color-bg-interactive-error-strong-active,#b90000);--wp-ui-button-foreground-color:var(--wpds-color-fg-interactive-error-strong,#f2efef);--wp-ui-button-foreground-color-active:var(--wpds-color-fg-interactive-error-strong-active,#f2efef)}}"));
   document.head.appendChild(style);
 }
-var style_default2 = { "header": "_837a6eb481252f50__header", "error-message": "dbff6618234a2a93__error-message", "irreversible-action": "_2ddc2fc9155a1dad__irreversible-action" };
+var style_default2 = { "error-message": "dbff6618234a2a93__error-message", "footer-column": "_66cf5fe0c6a030bd__footer-column", "irreversible-action": "_2ddc2fc9155a1dad__irreversible-action" };
 
 // packages/ui/src/alert-dialog/popup.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -70,46 +93,115 @@ var ThemeProvider = (0, import_lock_unlock.unlock)(import_theme.privateApis).The
 var Popup = (0, import_element.forwardRef)(
   function AlertDialogPopup({
     className,
+    portal,
     intent = "default",
     title,
     description,
     children,
     confirmButtonText = (0, import_i18n.__)("OK"),
     cancelButtonText = (0, import_i18n.__)("Cancel"),
+    stickyHeader = true,
+    stickyFooter = true,
+    initialFocus,
+    finalFocus,
     ...props
   }, ref) {
     const { phase, showSpinner, errorMessage, confirm } = (0, import_element.useContext)(import_context.AlertDialogContext);
+    const { ref: scrollStateRef, onScroll } = (0, import_use_overlay_scroll_state_attributes.useOverlayScrollStateAttributes)();
+    const { resolvedInitialFocus, popupRef } = (0, import_use_deprioritized_initial_focus.useDeprioritizedInitialFocus)(
+      {
+        initialFocus,
+        deprioritizedAttributes: [import_use_overlay_scroll_state_attributes.SCROLL_CONTAINER_ATTR]
+      }
+    );
+    const mergedRef = (0, import_compose.useMergeRefs)([ref, popupRef]);
     const confirmClassName = intent === "irreversible" ? style_default2["irreversible-action"] : void 0;
     const buttonsDisabled = phase !== "idle" || void 0;
-    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_alert_dialog.AlertDialog.Portal, { children: [
+    const headerElement = /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: overlay_chrome_default.header, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      import_text.Text,
+      {
+        variant: "heading-xl",
+        render: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_alert_dialog.AlertDialog.Title, {}),
+        className: overlay_chrome_default.title,
+        children: title
+      }
+    ) });
+    const footerElement = /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+      "div",
+      {
+        className: (0, import_clsx.default)(
+          overlay_chrome_default.footer,
+          style_default2["footer-column"]
+        ),
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+            import_stack.Stack,
+            {
+              direction: "row",
+              gap: "sm",
+              justify: "flex-end",
+              align: "center",
+              children: [
+                /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                  import_alert_dialog.AlertDialog.Close,
+                  {
+                    render: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_button.Button, { variant: "minimal" }),
+                    disabled: buttonsDisabled,
+                    children: cancelButtonText
+                  }
+                ),
+                /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+                  import_button.Button,
+                  {
+                    className: confirmClassName,
+                    onClick: confirm,
+                    loading: showSpinner || void 0,
+                    disabled: buttonsDisabled,
+                    children: confirmButtonText
+                  }
+                )
+              ]
+            }
+          ),
+          errorMessage && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+            import_text.Text,
+            {
+              variant: "body-sm",
+              className: style_default2["error-message"],
+              children: errorMessage
+            }
+          )
+        ]
+      }
+    );
+    const portalChildren = /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_alert_dialog.AlertDialog.Backdrop, { className: style_default.backdrop }),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ThemeProvider, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
         import_alert_dialog.AlertDialog.Popup,
         {
-          ref,
+          ref: mergedRef,
           className: (0, import_clsx.default)(
             style_default.popup,
             className,
             style_default["is-medium"]
           ),
+          initialFocus: resolvedInitialFocus,
+          finalFocus,
           ...props,
+          "data-wp-ui-overlay-modal": "",
           children: [
+            stickyHeader && headerElement,
             /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
-              import_stack.Stack,
+              "div",
               {
-                direction: "column",
-                gap: "sm",
-                className: style_default2.header,
+                ref: scrollStateRef,
+                className: (0, import_clsx.default)(
+                  overlay_chrome_default.content,
+                  focus_default["outset-ring--focus-visible"]
+                ),
+                onScroll,
                 children: [
-                  /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-                    import_text.Text,
-                    {
-                      variant: "heading-xl",
-                      render: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_alert_dialog.AlertDialog.Title, {}),
-                      className: style_default.title,
-                      children: title
-                    }
-                  ),
+                  !stickyHeader && headerElement,
                   description && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
                     import_text.Text,
                     {
@@ -117,45 +209,18 @@ var Popup = (0, import_element.forwardRef)(
                       render: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_alert_dialog.AlertDialog.Description, {}),
                       children: description
                     }
-                  )
+                  ),
+                  children,
+                  !stickyFooter && footerElement
                 ]
               }
             ),
-            children,
-            /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_stack.Stack, { direction: "column", gap: "md", children: [
-              /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: style_default.footer, children: [
-                /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-                  import_alert_dialog.AlertDialog.Close,
-                  {
-                    render: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_button.Button, { variant: "minimal" }),
-                    disabled: buttonsDisabled,
-                    children: cancelButtonText
-                  }
-                ),
-                /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-                  import_button.Button,
-                  {
-                    className: confirmClassName,
-                    onClick: confirm,
-                    loading: showSpinner || void 0,
-                    disabled: buttonsDisabled,
-                    children: confirmButtonText
-                  }
-                )
-              ] }),
-              errorMessage && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-                import_text.Text,
-                {
-                  variant: "body-sm",
-                  className: style_default2["error-message"],
-                  children: errorMessage
-                }
-              )
-            ] })
+            stickyFooter && footerElement
           ]
         }
       ) })
     ] });
+    return (0, import_render_portal_with_children.renderPortalWithChildren)(portal, /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_portal.Portal, {}), portalChildren);
   }
 );
 // Annotate the CommonJS export names for ESM import in node: