@wordpress/ui 0.11.0 → 0.12.0

package/src/utils/css/overlay-chrome.module.css

@@ -0,0 +1,222 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {
+	/*
+	 * Shared chrome + scroll-container primitives for overlay popups
+	 * (Dialog, AlertDialog, Drawer).
+	 *
+	 * Layout model: the popup is a vertical flex column with three regions
+	 * — `.header`, `.content`, `.footer`. Only `.content` scrolls; the
+	 * chrome sits at the popup's block-axis edges as natural flex siblings.
+	 *
+	 * Sticky opt-out for `Dialog` / `Drawer` is expressed in the DOM by
+	 * placing `Dialog.Header` / `Dialog.Footer` (or the Drawer equivalents)
+	 * inside `Dialog.Content` / `Drawer.Content` so they scroll with the
+	 * body; AlertDialog exposes the same choice via `stickyHeader` /
+	 * `stickyFooter` props, since it owns its internal DOM.
+	 */
+
+	/*
+	 * Chrome: flex row, no background (the popup already paints it), no
+	 * sticky positioning. Block-axis padding is asymmetric: the outer
+	 * side (popup edge) uses `padding-2xl` to match the inset that used
+	 * to live on the popup; the inner side (toward `.content`) uses the
+	 * tokenized `gap-lg` in full.
+	 *
+	 * No separator border here — the base chrome has none. The pinned
+	 * case (where a separator is needed) adds a `border-block-*: 1px
+	 * solid transparent` on the inner side and subtracts 1px from that
+	 * same padding so the chrome's overall border-box height stays
+	 * identical to the non-pinned case. See the `:has(~ .content)` /
+	 * `.content ~` rules below.
+	 *
+	 * `min-height` on `.header` keeps the header footprint stable whether
+	 * or not a close icon is rendered (notably the AlertDialog case, which
+	 * has no close button).
+	 */
+	.header {
+		display: flex;
+		align-items: center;
+		gap: var(--wpds-dimension-gap-sm);
+		padding-block: var(--wpds-dimension-padding-2xl) var(--wpds-dimension-gap-lg);
+		padding-inline: var(--wpds-dimension-padding-2xl);
+		/* TODO: refactor to a DS element size token when available. */
+		min-height: 32px;
+	}
+
+	.footer {
+		display: flex;
+		justify-content: flex-end;
+		align-items: center;
+		gap: var(--wpds-dimension-gap-sm);
+		padding-block: var(--wpds-dimension-gap-lg) var(--wpds-dimension-padding-2xl);
+		padding-inline: var(--wpds-dimension-padding-2xl);
+	}
+
+	/*
+	 * Overlay heading defaults: anchor the title to the inline start and
+	 * set the neutral text color explicitly. `--_gcd-heading-color` and
+	 * `--_gcd-heading-margin` defend against the heading-reset rules in
+	 * `global-css-defense.module.css`, which would otherwise take over a
+	 * `<h2>` rendered via `Text`.
+	 */
+	.title {
+		color: var(--wpds-color-fg-content-neutral);
+		--_gcd-heading-color: var(--wpds-color-fg-content-neutral);
+
+		margin-inline-end: auto;
+		--_gcd-heading-margin: 0 auto 0 0;
+
+		&:dir(rtl) {
+			--_gcd-heading-margin: 0 0 0 auto;
+		}
+	}
+
+	/*
+	 * Scroll container. `flex: 1 1 auto` + `min-block-size: 0` lets it
+	 * shrink below its content size so `overflow-block: auto` can actually
+	 * show a scrollbar when content exceeds the available space. Default
+	 * padding is `padding-2xl` on all sides; the yield rules below strip
+	 * block padding when chrome occupies that edge.
+	 *
+	 * Scrolling is intentionally block-axis-only. `overflow-inline: hidden`
+	 * clips wide content instead of introducing a horizontal scrollbar:
+	 * the sibling chrome doesn't scroll inline, the popup edge already
+	 * clips, and `useOverlayScrollStateAttributes` only tracks block-axis
+	 * overflow (tabindex + separator state). Overlay consumers should
+	 * constrain content width rather than rely on horizontal scroll.
+	 */
+	.content {
+		flex: 1 1 auto;
+		min-block-size: 0;
+		overflow-block: auto;
+		overflow-inline: hidden;
+		padding: var(--wpds-dimension-padding-2xl);
+
+		/*
+		 * The shared `outset-ring--focus-visible` utility (composed by
+		 * the Content components) uses an `outline-offset` of `+1px`,
+		 * which for this scroll container would put the ring outside
+		 * the popup's rounded corners and have it clipped by the
+		 * popup's `overflow: hidden`. Inset the ring by the focus
+		 * width instead, so it sits flush inside the content box.
+		 *
+		 * The shared utility's transition shorthand (`transition:
+		 * outline …`) only animates outline-color and outline-width,
+		 * not outline-offset, so the negative offset applied here is
+		 * static — visually, the ring still fades in/out via color
+		 * change while the offset stays put.
+		 */
+		&:focus-visible {
+			outline-offset: calc(var(--wpds-border-width-focus) * -1);
+		}
+	}
+
+	/*
+	 * Pinned chrome: reserve 1px on the inner side for the separator
+	 * border and subtract that same 1px from the adjacent padding. Net
+	 * effect on block-axis height is zero — the chrome's overall
+	 * border-box matches the non-pinned case — while the border provides
+	 * a fixed slot that the scroll-state rules below colorize.
+	 *
+	 * `.content` then drops its matching block-axis padding on that
+	 * edge, because the chrome already supplies the popup-edge
+	 * `padding-2xl` + inner `gap-lg`.
+	 *
+	 * Sibling relationships intentionally use the general-sibling
+	 * combinator (`~`) and `:has(~ …)` instead of the adjacent
+	 * combinator, so an extra element between header / content / footer
+	 * (custom wrappers, an a11y live region, etc.) doesn't silently
+	 * break the pinned layout. The expected DOM shape is still
+	 * header → content → footer; additional siblings in between are
+	 * tolerated.
+	 */
+	.header:has(~ .content) {
+		padding-block-end: calc(var(--wpds-dimension-gap-lg) - 1px);
+		border-block-end: 1px solid transparent;
+	}
+
+	.header ~ .content {
+		padding-block-start: 0;
+	}
+
+	.content ~ .footer {
+		padding-block-start: calc(var(--wpds-dimension-gap-lg) - 1px);
+		border-block-start: 1px solid transparent;
+	}
+
+	.content:has(~ .footer) {
+		padding-block-end: 0;
+	}
+
+	/*
+	 * Non-pinned case: when `.header` / `.footer` live inside `.content`
+	 * (scrolls with body). The scroll container already supplies the
+	 * inline popup-edge padding, so nested chrome always collapses its
+	 * own `padding-inline` regardless of its position inside `.content`
+	 * (no `:first-child` / `:last-child` guard). Block-axis padding is
+	 * only collapsed at the scroll edges — the `:first-child` /
+	 * `:last-child` rules keep the body's `gap-lg` visual separation
+	 * between the chrome and any preceding / following siblings inside
+	 * `.content`. No border — the separator is specific to the pinned
+	 * case.
+	 */
+	.content > .header {
+		padding-inline: 0;
+	}
+
+	.content > .header:first-child {
+		padding-block-start: 0;
+	}
+
+	.content > .footer {
+		padding-inline: 0;
+	}
+
+	.content > .footer:last-child {
+		padding-block-end: 0;
+	}
+
+	/*
+	 * Separator coloring. The transparent border on the pinned chrome is
+	 * colorized when the adjacent scroll container reports off-screen
+	 * content in that direction. Toggling the color (not the border's
+	 * existence) means no layout shift on scroll.
+	 *
+	 * `useOverlayScrollStateAttributes` owns the
+	 * `data-wp-ui-overlay-scrolled-from-*` toggles, so CSS handles the
+	 * visual state without React re-rendering on scroll.
+	 *
+	 * Forced-colors note: `border-color: transparent` is preserved as-is
+	 * in forced-colors mode per spec, so the default (non-scrolled)
+	 * state stays invisible. When the color toggles to a token value
+	 * below, the UA substitutes a system color (typically `CanvasText`),
+	 * so the separator remains visible in forced-colors mode without
+	 * any additional rules.
+	 */
+	.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);
+	}
+
+	[data-wp-ui-overlay-scroll-container][data-wp-ui-overlay-scrolled-from-bottom] ~ .footer {
+		border-block-start-color: var(--wpds-color-stroke-surface-neutral);
+	}
+
+	/*
+	 * `overscroll-behavior: contain` stops scroll chaining from the overlay
+	 * to whatever sits behind it. We only want that when the overlay is
+	 * modal: a non-modal overlay lets the page underneath remain
+	 * interactive, and chaining scroll to the page there is the intuitive
+	 * behavior.
+	 *
+	 * `data-wp-ui-overlay-modal` is toggled on the popup by each component
+	 * (Dialog / Drawer mirror their `modal` prop; AlertDialog is always
+	 * modal). The scroll container always lives inside the popup —
+	 * `Dialog.Content` / `Drawer.Content` for the public API, or an
+	 * internal container for AlertDialog — so a single descendant
+	 * selector anchored at the modal popup covers all three.
+	 */
+	[data-wp-ui-overlay-modal] [data-wp-ui-overlay-scroll-container] {
+		overscroll-behavior: contain;
+	}
+}

package/src/utils/render-portal-with-children.ts

@@ -0,0 +1,27 @@
+import { cloneElement } from '@wordpress/element';
+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 function renderPortalWithChildren(
+	portal: ReactElement | undefined,
+	defaultPortal: ReactElement,
+	children: ReactNode
+): ReactElement {
+	const rootPortal = portal ?? defaultPortal;
+
+	return cloneElement( rootPortal, {
+		children,
+	} );
+}

package/src/utils/test/use-deprioritized-initial-focus.test.tsx

@@ -17,7 +17,7 @@ function TestHarness( {
 } ) {
 	const result = useDeprioritizedInitialFocus( {
 		initialFocus,
-		deprioritizedAttribute: ATTR,
+		deprioritizedAttributes: [ ATTR ],
 	} );
 
 	useEffect( () => {
@@ -156,7 +156,7 @@ describe( 'useDeprioritizedInitialFocus', () => {
 			} ) {
 				const result = useDeprioritizedInitialFocus( {
 					initialFocus: undefined,
-					deprioritizedAttribute: ATTR,
+					deprioritizedAttributes: [ ATTR ],
 				} );
 
 				useEffect( () => {
@@ -200,7 +200,7 @@ describe( 'useDeprioritizedInitialFocus', () => {
 			} ) {
 				const result = useDeprioritizedInitialFocus( {
 					initialFocus: undefined,
-					deprioritizedAttribute: ATTR,
+					deprioritizedAttributes: [ ATTR ],
 				} );
 
 				useEffect( () => {

package/src/utils/use-deprioritized-initial-focus.ts

@@ -1,5 +1,5 @@
 import type { Popover as _Popover } from '@base-ui/react/popover';
-import { useMemo, useRef } from '@wordpress/element';
+import { useRef } from '@wordpress/element';
 import { tabbable } from 'tabbable';
 
 /**
@@ -24,39 +24,43 @@ const getTabbableOptions = () => ( {
 
 /**
  * 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 function useDeprioritizedInitialFocus( {
 	initialFocus,
-	deprioritizedAttribute,
+	deprioritizedAttributes,
 }: {
 	initialFocus: InitialFocus;
-	deprioritizedAttribute: string;
+	deprioritizedAttributes: string[];
 } ) {
 	const popupRef = useRef< HTMLDivElement >( null );
 
-	const resolvedInitialFocus = useMemo( (): InitialFocus => {
-		if ( initialFocus !== undefined && initialFocus !== true ) {
-			return initialFocus;
-		}
-
-		return ( interactionType ): HTMLElement | boolean | null => {
+	// Returning a fresh callback on every render is intentional. Base UI
+	// stores `initialFocus` via `useValueAsRef` (see its FloatingFocusManager
+	// source) and reads it through `ref.current` only at open time, so
+	// reference identity doesn't affect behavior. Skipping `useMemo` also
+	// avoids either forcing callers to memoize their attributes array or
+	// fighting the React Compiler with a stringified dep key.
+	let resolvedInitialFocus: InitialFocus = initialFocus;
+	if ( initialFocus === undefined || initialFocus === true ) {
+		resolvedInitialFocus = ( interactionType ) => {
 			if ( interactionType === 'touch' ) {
 				return popupRef.current ?? true;
 			}
@@ -70,7 +74,9 @@ export function useDeprioritizedInitialFocus( {
 			for ( const el of tabbables ) {
 				if (
 					el instanceof HTMLElement &&
-					! el.hasAttribute( deprioritizedAttribute )
+					! deprioritizedAttributes.some( ( attr ) =>
+						el.hasAttribute( attr )
+					)
 				) {
 					return el;
 				}
@@ -78,7 +84,7 @@ export function useDeprioritizedInitialFocus( {
 
 			return true;
 		};
-	}, [ initialFocus, deprioritizedAttribute ] );
+	}
 
 	return { resolvedInitialFocus, popupRef };
 }

package/src/utils/use-overlay-scroll-state-attributes.ts

@@ -0,0 +1,272 @@
+import type { UIEvent, UIEventHandler } from 'react';
+import { useCallback, useLayoutEffect, useState } from '@wordpress/element';
+
+export const SCROLL_CONTAINER_ATTR = 'data-wp-ui-overlay-scroll-container';
+const SCROLLED_FROM_TOP_ATTR = 'data-wp-ui-overlay-scrolled-from-top';
+const SCROLLED_FROM_BOTTOM_ATTR = 'data-wp-ui-overlay-scrolled-from-bottom';
+/**
+ * Marks a `tabindex` that this hook installed, so subsequent runs can tell
+ * a hook-managed tabindex apart from one the consumer set on the element
+ * themselves.
+ *
+ * Internal: the constant is not exported, but the literal string is named
+ * in the public JSDoc on `useOverlayScrollStateAttributes` so consumers
+ * grepping for "why does this element have a `tabindex='0'` I didn't set?"
+ * can find the breadcrumb. If this string changes, update the JSDoc too.
+ */
+const SCROLL_TABBABLE_FLAG_ATTR = 'data-wp-ui-overlay-scroll-tabbable';
+
+/**
+ * Allow fractional-pixel rounding when comparing scroll offsets. Browsers can
+ * report `scrollTop + clientHeight` as slightly less than `scrollHeight` even
+ * when fully scrolled to the bottom.
+ */
+const SCROLL_END_EPSILON = 1;
+
+/**
+ * Detect consumer takeover of a previously hook-managed `tabindex` after the
+ * hook had already installed its own: if the flag is set but the current
+ * `tabindex` is no longer `"0"`, the consumer has overridden our value. Drop
+ * the flag so subsequent ticks treat the `tabindex` as consumer-owned and
+ * never touch it again.
+ *
+ * Limitation: the heuristic compares the DOM attribute, so a consumer who
+ * passes `tabIndex={ 0 }` explicitly is indistinguishable from our own
+ * managed `"0"` and would still be cleaned up on the next non-overflow
+ * tick. See the contract paragraph on `useOverlayScrollStateAttributes`.
+ *
+ * @param el The scroll container.
+ */
+function reconcileTabbableFlag( el: HTMLElement ) {
+	if (
+		el.hasAttribute( SCROLL_TABBABLE_FLAG_ATTR ) &&
+		el.getAttribute( 'tabindex' ) !== '0'
+	) {
+		el.removeAttribute( SCROLL_TABBABLE_FLAG_ATTR );
+	}
+}
+
+function updateScrollAttributes( el: HTMLElement ) {
+	const { scrollTop, clientHeight, scrollHeight } = el;
+	const overflows = scrollHeight - clientHeight > SCROLL_END_EPSILON;
+
+	el.toggleAttribute( SCROLLED_FROM_TOP_ATTR, scrollTop > 0 );
+	el.toggleAttribute(
+		SCROLLED_FROM_BOTTOM_ATTR,
+		scrollTop + clientHeight < scrollHeight - SCROLL_END_EPSILON
+	);
+
+	// Keyboard-scrollable regions must be reachable via Tab (WCAG 2.1.1),
+	// but adding a stray tab stop to a non-scrolling `<div>` is an
+	// anti-pattern. Toggle `tabindex="0"` only while the element actually
+	// overflows. The flag attribute guards against clobbering a
+	// consumer-supplied tabindex: we only touch attributes we installed.
+
+	// Takeover-after-install: detect a consumer who started overriding
+	// our managed `"0"` *after* the hook installed it (e.g. a re-render
+	// passing `tabIndex={ -1 }`). The flag is dropped so the install /
+	// cleanup branches below leave the consumer's value untouched.
+	reconcileTabbableFlag( el );
+
+	if ( overflows ) {
+		// Pre-install opt-out: a consumer-supplied `tabindex` (including
+		// `tabindex="-1"` to hide the region from Tab order) keeps its
+		// value because the flag is never installed in the first place.
+		// If that consumer-supplied value is later *removed*, the hook
+		// will install its own on the next overflow tick — the DOM
+		// attribute alone can't distinguish a prior explicit opt-out
+		// from an unconfigured state.
+		if (
+			! el.hasAttribute( SCROLL_TABBABLE_FLAG_ATTR ) &&
+			el.getAttribute( 'tabindex' ) === null
+		) {
+			el.setAttribute( 'tabindex', '0' );
+			el.setAttribute( SCROLL_TABBABLE_FLAG_ATTR, '' );
+		}
+	} else if ( el.hasAttribute( SCROLL_TABBABLE_FLAG_ATTR ) ) {
+		el.removeAttribute( 'tabindex' );
+		el.removeAttribute( SCROLL_TABBABLE_FLAG_ATTR );
+	}
+}
+
+const HOOK_OWNED_ATTRS = [
+	SCROLL_CONTAINER_ATTR,
+	SCROLLED_FROM_TOP_ATTR,
+	SCROLLED_FROM_BOTTOM_ATTR,
+] as const;
+
+function cleanupScrollAttributes( el: HTMLElement ) {
+	for ( const attr of HOOK_OWNED_ATTRS ) {
+		el.removeAttribute( attr );
+	}
+	// Reconcile first so a flag left over from a consumer-takeover never
+	// causes us to clobber the consumer's `tabindex` here.
+	reconcileTabbableFlag( el );
+	// After reconciliation the flag is set only when the current
+	// `tabindex` is still `"0"` (i.e. ours). Any other value belongs to
+	// the consumer and is left alone.
+	if ( el.hasAttribute( SCROLL_TABBABLE_FLAG_ATTR ) ) {
+		el.removeAttribute( 'tabindex' );
+		el.removeAttribute( SCROLL_TABBABLE_FLAG_ATTR );
+	}
+}
+
+/**
+ * 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 function useOverlayScrollStateAttributes<
+	T extends HTMLElement = HTMLElement,
+>( onScroll?: UIEventHandler< T > | undefined ) {
+	const [ node, setNode ] = useState< T | null >( null );
+
+	const ref = useCallback( ( el: T | null ) => {
+		setNode( el );
+	}, [] );
+
+	useLayoutEffect( () => {
+		if ( ! node ) {
+			return;
+		}
+
+		node.setAttribute( SCROLL_CONTAINER_ATTR, '' );
+		updateScrollAttributes( node );
+
+		if ( typeof ResizeObserver === 'undefined' ) {
+			return () => {
+				cleanupScrollAttributes( node );
+			};
+		}
+
+		const resizeObserver = new ResizeObserver( () => {
+			updateScrollAttributes( node );
+		} );
+		resizeObserver.observe( node );
+		for ( const child of Array.from( node.children ) ) {
+			resizeObserver.observe( child );
+		}
+
+		let mutationObserver: MutationObserver | undefined;
+		if ( typeof MutationObserver !== 'undefined' ) {
+			mutationObserver = new MutationObserver( ( records ) => {
+				for ( const record of records ) {
+					// Only direct-child additions/removals affect what the
+					// ResizeObserver is observing; deeper descendant changes
+					// reach us through this callback for attribute refresh,
+					// but we don't observe them individually to keep the
+					// cost bounded on large subtrees.
+					if ( record.target === node ) {
+						for ( const added of Array.from( record.addedNodes ) ) {
+							if ( added instanceof Element ) {
+								resizeObserver.observe( added );
+							}
+						}
+						for ( const removed of Array.from(
+							record.removedNodes
+						) ) {
+							if ( removed instanceof Element ) {
+								resizeObserver.unobserve( removed );
+							}
+						}
+					}
+				}
+				updateScrollAttributes( node );
+			} );
+			// Direct children only — see the JSDoc above for why we
+			// intentionally don't observe the full subtree.
+			mutationObserver.observe( node, {
+				childList: true,
+			} );
+		}
+
+		return () => {
+			resizeObserver.disconnect();
+			mutationObserver?.disconnect();
+			cleanupScrollAttributes( node );
+		};
+	}, [ node ] );
+
+	const handleScroll = useCallback(
+		( event: UIEvent< T > ) => {
+			updateScrollAttributes( event.currentTarget );
+			onScroll?.( event );
+		},
+		[ onScroll ]
+	);
+
+	return { ref, onScroll: handleScroll };
+}

package/src/utils/use-schedule-validation.ts

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useRef } from '@wordpress/element';
+
+/**
+ * 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 function useScheduleValidation( validate: () => void ) {
+	const validateRef = useRef( validate );
+	validateRef.current = validate;
+
+	const timerRef = useRef< ReturnType< typeof setTimeout > | null >( null );
+	const unmountedRef = useRef( false );
+
+	const scheduleValidation = useCallback( () => {
+		if ( unmountedRef.current ) {
+			return;
+		}
+		if ( timerRef.current ) {
+			clearTimeout( timerRef.current );
+		}
+		timerRef.current = setTimeout( () => {
+			validateRef.current();
+			timerRef.current = null;
+		}, 0 );
+	}, [] );
+
+	useEffect( () => {
+		unmountedRef.current = false;
+		return () => {
+			unmountedRef.current = true;
+			if ( timerRef.current ) {
+				clearTimeout( timerRef.current );
+			}
+		};
+	}, [] );
+
+	return scheduleValidation;
+}

package/src/visually-hidden/stories/index.story.tsx

@@ -3,6 +3,7 @@ import { useId } from '@wordpress/element';
 import { VisuallyHidden } from '../';
 
 const meta: Meta< typeof VisuallyHidden > = {
+	tags: [ 'manifest' ],
 	title: 'Design System/Components/VisuallyHidden',
 	component: VisuallyHidden,
 };