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

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

@@ -1,18 +1,26 @@
-import type { ReactNode } from 'react';
-import type { Tooltip } from '@base-ui/react/tooltip';
+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 RootProps = Pick<Tooltip.Root.Props, 'disabled' | 'children'>;
-export type ProviderProps = Pick<Tooltip.Provider.Props, 'delay' | 'children'>;
+export type PortalProps = ComponentPropsWithoutRef<typeof _Tooltip.Portal>;
+export type RootProps = Pick<_Tooltip.Root.Props, 'disabled' | 'children'>;
+export type ProviderProps = Pick<_Tooltip.Provider.Props, 'delay' | 'children'>;
 export interface TriggerProps extends ComponentProps<'button'> {
     /**
      * The content to be rendered inside the component.
      */
     children?: ReactNode;
 }
-export interface PopupProps extends ComponentProps<'div'>, Pick<Tooltip.Positioner.Props, 'align' | 'side' | 'sideOffset'> {
+export interface PopupProps extends ComponentProps<'div'>, Pick<_Tooltip.Positioner.Props, 'align' | 'side' | 'sideOffset'> {
     /**
      * The content to be rendered inside the component.
      */
     children?: ReactNode;
+    /**
+     * Optional portal element, typically `<Tooltip.Portal />` with custom
+     * `container`. When omitted, `Tooltip.Popup` uses `Tooltip.Portal` with
+     * default props. Do not pass `children` on the portal element; they would
+     * be ignored.
+     */
+    portal?: ReactElement<Omit<PortalProps, '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,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG,IAAI,CAAE,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAE,CAAC;AAE5E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,EACtB,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,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAE;IAClE;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB"}
+{"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"}

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

@@ -0,0 +1,14 @@
+type OverlayModalProviderProps<Modal> = {
+    modal: Modal;
+    children: React.ReactNode;
+};
+/**
+ * Creates a modal context pair (`Provider` + `useModal`) for overlay
+ * primitives like Dialog and Drawer.
+ */
+export declare function createOverlayModalContext<Modal>(initialValue: Modal): {
+    Provider: ({ modal, children, }: OverlayModalProviderProps<Modal>) => import("react").JSX.Element;
+    useModal: () => Modal;
+};
+export {};
+//# sourceMappingURL=create-overlay-modal-context.d.ts.map

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

@@ -0,0 +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"}

package/build-types/utils/create-overlay-title-validation.d.ts

@@ -0,0 +1,15 @@
+type OverlayValidationContextType = {
+    registerTitle: (element: HTMLElement | null) => () => void;
+};
+type OverlayValidationProviderProps = {
+    children: React.ReactNode;
+};
+/**
+ * Creates development-only title validation helpers for overlay primitives.
+ */
+export declare function createOverlayTitleValidation(componentName: string): {
+    ValidationProvider: ({ children, }: OverlayValidationProviderProps) => import("react").JSX.Element;
+    useValidationContext: () => OverlayValidationContextType | null;
+};
+export {};
+//# sourceMappingURL=create-overlay-title-validation.d.ts.map

package/build-types/utils/create-overlay-title-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-overlay-title-validation.d.ts","sourceRoot":"","sources":["../../src/utils/create-overlay-title-validation.tsx"],"names":[],"mappings":"AAgBA,KAAK,4BAA4B,GAAG;IACnC,aAAa,EAAE,CAAE,OAAO,EAAE,WAAW,GAAG,IAAI,KAAM,MAAM,IAAI,CAAC;CAC7D,CAAC;AAEF,KAAK,8BAA8B,GAAG;IACrC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC1B,CAAC;AAEF;;GAEG;AACH,wBAAgB,4BAA4B,CAAE,aAAa,EAAE,MAAM;wCAoB/D,8BAA8B;;EAoEjC"}

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

@@ -0,0 +1,16 @@
+import type { ReactElement, ReactNode } from 'react';
+/**
+ * Renders overlay markup (`children`) through an optional `portal` element from
+ * `portal={ <Component.Portal … /> }`, or through the package default portal.
+ *
+ * Shared by overlay `Popup` components so portal merge behavior stays consistent.
+ *
+ * @param portal        Optional element from the `portal` prop (should have no
+ *                      `children`; callers type this via `Omit<PortalProps,'children'>`).
+ *                      When omitted, `defaultPortal` is used. Injected `children`
+ *                      replace any subtree on the portal element.
+ * @param defaultPortal Unpopulated default portal element (e.g. `<Dialog.Portal />`).
+ * @param children      Popup subtree (backdrop, positioner, etc.) to inject as the portal’s children.
+ */
+export declare function renderPortalWithChildren(portal: ReactElement | undefined, defaultPortal: ReactElement, children: ReactNode): ReactElement;
+//# sourceMappingURL=render-portal-with-children.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-portal-with-children.d.ts","sourceRoot":"","sources":["../../src/utils/render-portal-with-children.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACvC,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,aAAa,EAAE,YAAY,EAC3B,QAAQ,EAAE,SAAS,GACjB,YAAY,CAMd"}

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

@@ -3,11 +3,15 @@ type HTMLAttributesWithRef<T extends ElementType = any> = HTMLAttributes<T> & {
     ref?: Ref<T> | undefined;
 };
 type ComponentRenderFn<Props> = (props: Props) => React.ReactElement<unknown>;
-export type ComponentProps<E extends ElementType> = Omit<ComponentPropsWithoutRef<E>, 'className' | 'children' | 'render'> & {
+export type ComponentProps<E extends ElementType> = Omit<ComponentPropsWithoutRef<E>, 'className' | 'children' | 'render' | 'style'> & {
     /**
-     * CSS class name to apply to the component.
+     * CSS class name to apply to the element.
      */
     className?: string;
+    /**
+     * CSS style to apply to the element.
+     */
+    style?: React.CSSProperties;
     /**
      * Replaces the component's default HTML element using a given React
      * element, or a function that returns a React element.

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,MAAM,OAAO,CAAC;AAEf,KAAK,qBAAqB,CAAE,CAAC,SAAS,WAAW,GAAG,GAAG,IACtD,cAAc,CAAE,CAAC,CAAE,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAE,CAAC,CAAE,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,KAAK,iBAAiB,CAAE,KAAK,IAAK,CACjC,KAAK,EAAE,KAAK,KACR,KAAK,CAAC,YAAY,CAAE,OAAO,CAAE,CAAC;AAEnC,MAAM,MAAM,cAAc,CAAE,CAAC,SAAS,WAAW,IAAK,IAAI,CACzD,wBAAwB,CAAE,CAAC,CAAE,EAC7B,WAAW,GAAG,UAAU,GAAG,QAAQ,CACnC,GAAG;IACH;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EACJ,iBAAiB,CAAE,qBAAqB,CAAE,GAC1C,KAAK,CAAC,YAAY,CAAE,MAAM,CAAE,MAAM,EAAE,OAAO,CAAE,CAAE,CAAC;CACnD,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,MAAM,OAAO,CAAC;AAEf,KAAK,qBAAqB,CAAE,CAAC,SAAS,WAAW,GAAG,GAAG,IACtD,cAAc,CAAE,CAAC,CAAE,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAE,CAAC,CAAE,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,KAAK,iBAAiB,CAAE,KAAK,IAAK,CACjC,KAAK,EAAE,KAAK,KACR,KAAK,CAAC,YAAY,CAAE,OAAO,CAAE,CAAC;AAEnC,MAAM,MAAM,cAAc,CAAE,CAAC,SAAS,WAAW,IAAK,IAAI,CACzD,wBAAwB,CAAE,CAAC,CAAE,EAC7B,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAC7C,GAAG;IACH;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAE5B;;;OAGG;IACH,MAAM,CAAC,EACJ,iBAAiB,CAAE,qBAAqB,CAAE,GAC1C,KAAK,CAAC,YAAY,CAAE,MAAM,CAAE,MAAM,EAAE,OAAO,CAAE,CAAE,CAAC;CACnD,CAAC"}

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

@@ -7,27 +7,28 @@ import type { Popover as _Popover } from '@base-ui/react/popover';
 type InitialFocus = _Popover.Popup.Props['initialFocus'];
 /**
  * Returns a resolved `initialFocus` value that deprioritizes elements
- * marked with a given data attribute (e.g. a close icon), and an internal
- * ref that must be merged onto the popup element.
+ * marked with any of the given data attributes (e.g. a close icon, a
+ * library-managed scroll container), and an internal ref that must be
+ * merged onto the popup element.
  *
  * When `initialFocus` is `undefined` or `true` (the default behavior),
  * the hook replaces it with a callback that:
  * 1. On touch interactions — focuses the popup element itself (preventing
  *    the virtual keyboard on Android), matching Base UI's default.
  * 2. On other interactions — returns the first tabbable element that does
- *    *not* carry `deprioritizedAttribute`. Falls back to Base UI's default
- *    when the deprioritized element is the only tabbable element.
+ *    *not* carry any of `deprioritizedAttributes`. Falls back to Base
+ *    UI's default when every tabbable element is deprioritized.
  *
  * All other `initialFocus` values (`false`, `RefObject`, callback) pass
  * through unchanged.
  *
  * @param props
- * @param props.initialFocus           The consumer-provided `initialFocus` value.
- * @param props.deprioritizedAttribute The data attribute whose elements should be deprioritized.
+ * @param props.initialFocus            The consumer-provided `initialFocus` value.
+ * @param props.deprioritizedAttributes The data attributes whose elements should be deprioritized.
  */
-export declare function useDeprioritizedInitialFocus({ initialFocus, deprioritizedAttribute, }: {
+export declare function useDeprioritizedInitialFocus({ initialFocus, deprioritizedAttributes, }: {
     initialFocus: InitialFocus;
-    deprioritizedAttribute: string;
+    deprioritizedAttributes: string[];
 }): {
     resolvedInitialFocus: boolean | import("react").RefObject<HTMLElement | null> | ((openType: import("@base-ui/utils/useEnhancedClickHandler").InteractionType) => void | boolean | HTMLElement | null) | undefined;
     popupRef: import("react").RefObject<HTMLDivElement>;

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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAAE,EAC7C,YAAY,EACZ,sBAAsB,GACtB,EAAE;IACF,YAAY,EAAE,YAAY,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;CAC/B;;;EAiCA"}
+{"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"}

package/build-types/utils/use-overlay-scroll-state-attributes.d.ts

@@ -0,0 +1,85 @@
+import type { UIEvent, UIEventHandler } from 'react';
+export declare const SCROLL_CONTAINER_ATTR = "data-wp-ui-overlay-scroll-container";
+/**
+ * Keeps `data-wp-ui-overlay-scrolled-from-top` and
+ * `data-wp-ui-overlay-scrolled-from-bottom` attributes in sync with a
+ * scrollable overlay element's scroll position, and marks the element with
+ * `data-wp-ui-overlay-scroll-container` so shared CSS (see
+ * `overlay-chrome.module.css`) can target it without coupling to a specific
+ * class name. Descendant selectors (e.g. sticky header/footer chrome) read
+ * these attributes to toggle their separator border without forcing a React
+ * re-render on every scroll frame.
+ *
+ * When the element overflows, a `tabindex="0"` is also installed so keyboard
+ * users can focus the region and arrow-scroll it (WCAG 2.1.1). The tabindex
+ * is removed again as soon as the element no longer overflows — a stray tab
+ * stop on a non-scrolling region is an anti-pattern. An internal flag
+ * attribute (`data-wp-ui-overlay-scroll-tabbable`) marks tabindex values
+ * the hook installed, so a consumer-supplied `tabindex` is never
+ * overwritten.
+ *
+ * Tabindex contract:
+ * - **Pre-install opt-out**: a `tabindex` set on the element before the
+ *   first overflow is detected is left alone forever. The flag is never
+ *   installed, so the hook never owns the attribute. (This means
+ *   `tabIndex={ -1 }` on `Dialog.Content` / `Drawer.Content` reliably
+ *   suppresses the auto tab stop.)
+ * - **Takeover after install**: if the consumer overrides the hook's
+ *   `"0"` with a *different* value after the fact, the flag is dropped
+ *   on the next tick (`reconcileTabbableFlag`) and the consumer's value
+ *   is preserved through subsequent overflow / non-overflow transitions
+ *   and through cleanup.
+ * - **Indistinguishable case**: a consumer who passes `tabIndex={ 0 }`
+ *   explicitly while the hook also has `"0"` installed cannot be
+ *   detected — the DOM attribute is identical to the hook-managed
+ *   value, so the hook will still strip it on the next non-overflow
+ *   tick. This is rarely intentional (the consumer's `0` matches the
+ *   hook's behavior anyway), but consumers needing a guaranteed
+ *   sticky `0` should avoid relying on it across overflow flips.
+ *
+ * Overflow detection is block-axis-only. Overlay popups are expected to
+ * constrain content width (`overlay-chrome.module.css` clips `.content`
+ * with `overflow-inline: hidden`); horizontal scrolling is intentionally
+ * not supported, so this hook doesn't toggle tabindex on inline-axis
+ * overflow and the scroll-state attributes don't track it.
+ *
+ * Returns a callback `ref` that the caller must attach to the scroll
+ * container, and an `onScroll` handler to wire up to the same element. A
+ * callback ref (not a `RefObject`) is used because overlay libraries like
+ * Base UI mount the popup DOM lazily when the overlay opens, so the
+ * attributes must be initialized the moment the node is attached, not when
+ * the host component first renders. `useState` also absorbs repeated
+ * attachments of the same node (Strict Mode remount, stable refs) without
+ * re-running the effect.
+ *
+ * Change detection combines a `ResizeObserver` scoped to the container
+ * and its direct children (to catch flex-layout growth) with a
+ * `MutationObserver` on direct-child additions/removals only (to keep
+ * the resize-observer set in sync as direct children come and go).
+ *
+ * Deeper subtree mutations are intentionally not observed: in practice,
+ * any descendant whose growth changes the scroll size also propagates a
+ * resize up the layout tree, so the existing `ResizeObserver` on direct
+ * children catches it. Watching the full subtree would fan out the
+ * mutation callback over every text-node insertion in content-heavy
+ * overlays (rich-text editors, virtualized lists), which isn't worth
+ * the cost of the rare deep-mutation-without-resize case. Revisit
+ * (and consider rAF-coalescing the callback) if a real consumer hits
+ * an attribute-staleness regression.
+ *
+ * Once CSS scroll-state container queries are supported across target
+ * browsers, both the data attributes and this hook can be replaced with
+ * `@container scroll-state(scrollable: top)` / `(scrollable: bottom)`.
+ * See: https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries
+ *
+ * @param onScroll Optional `onScroll` from the parent; invoked after the
+ *                 overlay scroll-state attributes are updated, so by the
+ *                 time this handler runs, `data-wp-ui-overlay-scrolled-*`
+ *                 on `event.currentTarget` already reflect the post-scroll
+ *                 state.
+ */
+export declare function useOverlayScrollStateAttributes<T extends HTMLElement = HTMLElement>(onScroll?: UIEventHandler<T> | undefined): {
+    ref: (el: T | null) => void;
+    onScroll: (event: UIEvent<T>) => void;
+};
+//# sourceMappingURL=use-overlay-scroll-state-attributes.d.ts.map

package/build-types/utils/use-overlay-scroll-state-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-overlay-scroll-state-attributes.d.ts","sourceRoot":"","sources":["../../src/utils/use-overlay-scroll-state-attributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAGrD,eAAO,MAAM,qBAAqB,wCAAwC,CAAC;AA8G3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,wBAAgB,+BAA+B,CAC9C,CAAC,SAAS,WAAW,GAAG,WAAW,EACjC,QAAQ,CAAC,EAAE,cAAc,CAAE,CAAC,CAAE,GAAG,SAAS;cAGb,CAAC,GAAG,IAAI;sBAmE7B,OAAO,CAAE,CAAC,CAAE;EAQtB"}

package/build-types/utils/use-schedule-validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Dev-only hook that returns a stable `scheduleValidation` function.
+ *
+ * Each call debounces to `setTimeout(…, 0)` so that rapid
+ * register / unregister cycles (e.g. React strict-mode double-mount)
+ * settle before the check runs. The timer is cleaned up on unmount,
+ * and calls after unmount are silently ignored.
+ *
+ * @param validate Callback that performs the actual validation.
+ *                 Stored in a ref — safe to pass an unstable closure.
+ */
+export declare function useScheduleValidation(validate: () => void): () => void;
+//# sourceMappingURL=use-schedule-validation.d.ts.map

package/build-types/utils/use-schedule-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-schedule-validation.d.ts","sourceRoot":"","sources":["../../src/utils/use-schedule-validation.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAE,QAAQ,EAAE,MAAM,IAAI,cA+B1D"}

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

@@ -4,4 +4,11 @@ declare const meta: Meta<typeof VisuallyHidden>;
 export default meta;
 type Story = StoryObj<typeof VisuallyHidden>;
 export declare const Default: Story;
+/**
+ * Use the `render` prop to change the underlying HTML element.
+ * By default, `VisuallyHidden` renders a `<div>`. Here it renders
+ * a `<label>` instead, keeping the native label–input association
+ * while hiding the label text visually.
+ */
+export declare const WithCustomElement: Story;
 //# sourceMappingURL=index.story.d.ts.map

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;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAErC,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,cAAc,CAGtC,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,KAAK,KAAK,GAAG,QAAQ,CAAE,OAAO,cAAc,CAAE,CAAC;AAE/C,eAAO,MAAM,OAAO,EAAE,KAUrB,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,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"}

package/build-types/visually-hidden/visually-hidden.d.ts

@@ -2,6 +2,24 @@ import type { VisuallyHiddenProps } from './types';
 /**
  * Visually hides content while keeping it accessible to screen readers.
  * Useful when providing context that's only meaningful to assistive technology.
+ *
+ * Renders a `<div>` by default. Use the `render` prop to swap the
+ * underlying element while preserving the visually-hidden behavior.
+ *
+ * ## Composing with other components
+ *
+ * When composing with another component that uses the `render` prop
+ * pattern, keep `VisuallyHidden` as the **host** (outer component) and
+ * pass the other component via `render`. This keeps the other
+ * component's HTML element and semantics intact, while `VisuallyHidden`
+ * only adds its hiding styles:
+ *
+ * ```jsx
+ * // OtherComponent keeps its semantic element (e.g. <h2>).
+ * <VisuallyHidden render={ <OtherComponent /> }>
+ *   Accessible text
+ * </VisuallyHidden>
+ * ```
  */
 export declare const VisuallyHidden: import("react").ForwardRefExoticComponent<VisuallyHiddenProps & import("react").RefAttributes<HTMLDivElement>>;
 //# sourceMappingURL=visually-hidden.d.ts.map

package/build-types/visually-hidden/visually-hidden.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"visually-hidden.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/visually-hidden.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAGnD;;;GAGG;AACH,eAAO,MAAM,cAAc,gHAa1B,CAAC"}
+{"version":3,"file":"visually-hidden.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/visually-hidden.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,cAAc,gHAiB1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/ui",
-	"version": "0.11.1-next.v.202604091042.0+668146787",
+	"version": "0.12.0",
 	"description": "Themeable React UI components for the WordPress Design System.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -43,16 +43,16 @@
 	"types": "build-types",
 	"sideEffects": false,
 	"dependencies": {
-		"@base-ui/react": "^1.3.0",
-		"@wordpress/a11y": "^4.43.1-next.v.202604091042.0+668146787",
-		"@wordpress/compose": "^7.43.1-next.v.202604091042.0+668146787",
-		"@wordpress/element": "^6.44.1-next.v.202604091042.0+668146787",
-		"@wordpress/i18n": "^6.17.1-next.v.202604091042.0+668146787",
-		"@wordpress/icons": "^12.1.1-next.v.202604091042.0+668146787",
-		"@wordpress/keycodes": "^4.43.1-next.v.202604091042.0+668146787",
-		"@wordpress/primitives": "^4.43.1-next.v.202604091042.0+668146787",
-		"@wordpress/private-apis": "^1.43.1-next.v.202604091042.0+668146787",
-		"@wordpress/theme": "^0.10.1-next.v.202604091042.0+668146787",
+		"@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",
 		"clsx": "^2.1.1",
 		"tabbable": "^6.4.0"
 	},
@@ -71,5 +71,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "73606df74f1c38a084bfa5db97205259ef817593"
+	"gitHead": "8c229eaed0e88c9827e2da3d73a78f9ddd77714b"
 }

package/src/alert-dialog/index.ts

@@ -1,3 +1,4 @@
 export { Root } from './root';
 export { Trigger } from './trigger';
 export { Popup } from './popup';
+export { Portal } from './portal';

package/src/alert-dialog/popup.tsx

@@ -1,18 +1,28 @@
 import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
 import clsx from 'clsx';
 import { forwardRef, useContext } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
 import {
 	type ThemeProvider as ThemeProviderType,
 	privateApis as themePrivateApis,
 } from '@wordpress/theme';
 
+import { renderPortalWithChildren } from '../utils/render-portal-with-children';
 import { Button } from '../button';
 import dialogStyles from '../dialog/style.module.css';
+import focusStyles from '../utils/css/focus.module.css';
+import overlayChromeStyles from '../utils/css/overlay-chrome.module.css';
+import { useDeprioritizedInitialFocus } from '../utils/use-deprioritized-initial-focus';
+import {
+	SCROLL_CONTAINER_ATTR,
+	useOverlayScrollStateAttributes,
+} from '../utils/use-overlay-scroll-state-attributes';
 import { unlock } from '../lock-unlock';
 import { Stack } from '../stack';
 import { Text } from '../text';
 import { AlertDialogContext } from './context';
+import { Portal } from './portal';
 import alertDialogStyles from './style.module.css';
 import type { PopupProps } from './types';
 
@@ -23,12 +33,17 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 	function AlertDialogPopup(
 		{
 			className,
+			portal,
 			intent = 'default',
 			title,
 			description,
 			children,
 			confirmButtonText = __( 'OK' ),
 			cancelButtonText = __( 'Cancel' ),
+			stickyHeader = true,
+			stickyFooter = true,
+			initialFocus,
+			finalFocus,
 			...props
 		},
 		ref
@@ -36,6 +51,32 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 		const { phase, showSpinner, errorMessage, confirm } =
 			useContext( AlertDialogContext );
 
+		/*
+		 * Scroll ownership lives on an internal scroll container so the
+		 * shared chrome CSS can target `[data-wp-ui-overlay-scroll-container]`
+		 * here the same way it does on Dialog.Content / Drawer.Content.
+		 * `stickyHeader` / `stickyFooter` control whether the chrome renders
+		 * as a sibling of the scroller (pinned) or inside it (scrolls with
+		 * the body).
+		 */
+		const { ref: scrollStateRef, onScroll } =
+			useOverlayScrollStateAttributes< HTMLDivElement >();
+
+		/*
+		 * Skip the internal scroll container during initial focus
+		 * resolution: when the body overflows, that container becomes
+		 * `tabindex="0"` (so keyboard users can arrow-scroll it) and
+		 * would otherwise win first-tabbable status over the action
+		 * buttons. Mirrors the same wiring on Dialog/Drawer popups.
+		 */
+		const { resolvedInitialFocus, popupRef } = useDeprioritizedInitialFocus(
+			{
+				initialFocus,
+				deprioritizedAttributes: [ SCROLL_CONTAINER_ATTR ],
+			}
+		);
+		const mergedRef = useMergeRefs( [ ref, popupRef ] );
+
 		const confirmClassName =
 			intent === 'irreversible'
 				? alertDialogStyles[ 'irreversible-action' ]
@@ -43,31 +84,83 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 
 		const buttonsDisabled = phase !== 'idle' || undefined;
 
-		return (
-			<_AlertDialog.Portal>
+		const headerElement = (
+			<div className={ overlayChromeStyles.header }>
+				<Text
+					variant="heading-xl"
+					render={ <_AlertDialog.Title /> }
+					className={ overlayChromeStyles.title }
+				>
+					{ title }
+				</Text>
+			</div>
+		);
+
+		const footerElement = (
+			<div
+				className={ clsx(
+					overlayChromeStyles.footer,
+					alertDialogStyles[ 'footer-column' ]
+				) }
+			>
+				<Stack
+					direction="row"
+					gap="sm"
+					justify="flex-end"
+					align="center"
+				>
+					<_AlertDialog.Close
+						render={ <Button variant="minimal" /> }
+						disabled={ buttonsDisabled }
+					>
+						{ cancelButtonText }
+					</_AlertDialog.Close>
+					<Button
+						className={ confirmClassName }
+						onClick={ confirm }
+						loading={ showSpinner || undefined }
+						disabled={ buttonsDisabled }
+					>
+						{ confirmButtonText }
+					</Button>
+				</Stack>
+				{ errorMessage && (
+					<Text
+						variant="body-sm"
+						className={ alertDialogStyles[ 'error-message' ] }
+					>
+						{ errorMessage }
+					</Text>
+				) }
+			</div>
+		);
+
+		const portalChildren = (
+			<>
 				<_AlertDialog.Backdrop className={ dialogStyles.backdrop } />
 				<ThemeProvider>
 					<_AlertDialog.Popup
-						ref={ ref }
+						ref={ mergedRef }
 						className={ clsx(
 							dialogStyles.popup,
 							className,
 							dialogStyles[ 'is-medium' ]
 						) }
+						initialFocus={ resolvedInitialFocus }
+						finalFocus={ finalFocus }
 						{ ...props }
+						data-wp-ui-overlay-modal=""
 					>
-						<Stack
-							direction="column"
-							gap="sm"
-							className={ alertDialogStyles.header }
+						{ stickyHeader && headerElement }
+						<div
+							ref={ scrollStateRef }
+							className={ clsx(
+								overlayChromeStyles.content,
+								focusStyles[ 'outset-ring--focus-visible' ]
+							) }
+							onScroll={ onScroll }
 						>
-							<Text
-								variant="heading-xl"
-								render={ <_AlertDialog.Title /> }
-								className={ dialogStyles.title }
-							>
-								{ title }
-							</Text>
+							{ ! stickyHeader && headerElement }
 							{ description && (
 								<Text
 									variant="body-md"
@@ -76,40 +169,16 @@ const Popup = forwardRef< HTMLDivElement, PopupProps >(
 									{ description }
 								</Text>
 							) }
-						</Stack>
-						{ children }
-						<Stack direction="column" gap="md">
-							<div className={ dialogStyles.footer }>
-								<_AlertDialog.Close
-									render={ <Button variant="minimal" /> }
-									disabled={ buttonsDisabled }
-								>
-									{ cancelButtonText }
-								</_AlertDialog.Close>
-								<Button
-									className={ confirmClassName }
-									onClick={ confirm }
-									loading={ showSpinner || undefined }
-									disabled={ buttonsDisabled }
-								>
-									{ confirmButtonText }
-								</Button>
-							</div>
-							{ errorMessage && (
-								<Text
-									variant="body-sm"
-									className={
-										alertDialogStyles[ 'error-message' ]
-									}
-								>
-									{ errorMessage }
-								</Text>
-							) }
-						</Stack>
+							{ children }
+							{ ! stickyFooter && footerElement }
+						</div>
+						{ stickyFooter && footerElement }
 					</_AlertDialog.Popup>
 				</ThemeProvider>
-			</_AlertDialog.Portal>
+			</>
 		);
+
+		return renderPortalWithChildren( portal, <Portal />, portalChildren );
 	}
 );
 

package/src/alert-dialog/portal.tsx

@@ -0,0 +1,17 @@
+import { AlertDialog as _AlertDialog } from '@base-ui/react/alert-dialog';
+import { forwardRef } from '@wordpress/element';
+import type { PortalProps } from './types';
+
+/**
+ * Root element that portals `AlertDialog` overlay content. Pass to
+ * `AlertDialog.Popup`'s `portal` prop to customize the portal target and
+ * wrapper. When `portal` is omitted, `AlertDialog.Popup` uses this component
+ * with default props.
+ */
+const Portal = forwardRef< HTMLDivElement, PortalProps >(
+	function AlertDialogPortal( props, ref ) {
+		return <_AlertDialog.Portal ref={ ref } { ...props } />;
+	}
+);
+
+export { Portal };