@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/Layer/outsidePress.ts

@@ -6,7 +6,9 @@
  * @file outsidePress.ts
  * @input Listens for pointerdown, pointerup and pointercancel on a document
  * @output Exports watchOutsidePress and useOutsidePress, which owns one watch
- *   for a component: start on show, stop on hide, stop on unmount; and the
+ *   for a component: start on show, stop on hide, stop on unmount;
+ *   noteOutsideDismissal and outsideDismissalCount, a per-document count of
+ *   layers that an outside press or focus move closed; and the
  *   inside tests a text field's owner runs: isPressInsideOwnedLayer for a
  *   press, isFocusInsideOwnedLayer for a blur
  * @position Internal to Layer; the outside-press dismissal for a manual
@@ -23,6 +25,20 @@
 
 import {useCallback, useEffect, useMemo, useRef} from 'react';
 
+// A modal host's backdrop press reads this. A press that closed a layer above
+// the host is that layer's, so the host stays open.
+const outsideDismissals = new WeakMap<Document, number>();
+
+/** Records that a layer in `doc` is closing because a press or focus went outside it. */
+export function noteOutsideDismissal(doc: Document): void {
+  outsideDismissals.set(doc, (outsideDismissals.get(doc) ?? 0) + 1);
+}
+
+/** How many layers an outside press has closed in `doc` so far. */
+export function outsideDismissalCount(doc: Document): number {
+  return outsideDismissals.get(doc) ?? 0;
+}
+
 /**
  * Watch the owner's document for a press outside, until the returned function
  * is called. The caller stops it when its layer hides and when it unmounts.
@@ -49,6 +65,7 @@ export function watchOutsidePress(
     const wasOutside = startedOutside;
     startedOutside = false;
     if (wasOutside && !isInside(event.composedPath())) {
+      noteOutsideDismissal(doc);
       onOutside();
     }
   };

package/src/Layer/preserveAnimations.ts

@@ -11,245 +11,23 @@
  *
  * Taking an element out of rendering cancels every CSS animation and
  * transition of it and its subtree. When it returns, the browser creates the
- * animations again from the stylesheet, at their start, and the transitions
- * not at all; script-created animations are untouched. `preserveAnimations`
- * reads every animation's state first and, afterwards, gives each recreated
- * CSS animation that state and resumes each cancelled transition with a
- * script animation at the same point.
- *
- * The state is read generically, from what the platform exposes: every
- * accessor with a setter on the animation's and its effect's prototype
- * chains, every field of the effect's timing, and its keyframes. Only values
- * that differ from the recreated animation's are written, so a value the
- * stylesheet controls stays under its control. A few members are not plain
- * state and are handled in their own step (`ORDERED`); the rest need no
- * handling (`DERIVED`). What cannot be carried over is the Animation and
- * effect objects themselves: the old ones are idle, their `addEventListener`
- * listeners and `finished`/`ready` promises stay with them, and the browser
- * fires `animationcancel`/`transitioncancel` for them and `animationstart`
+ * animations again from the stylesheet, at their start. It starts no
+ * transition but one from `@starting-style`, and script-created animations
+ * are untouched. `preserveAnimations` reads every animation's state first.
+ * Afterwards it gives each recreated CSS animation that state, and resumes
+ * each cancelled transition with a script animation at the same point. Any
+ * other animation the return started is finished, unless it never ends
+ * (motion/carryAnimations.ts). The browser fires
+ * `animationcancel`/`transitioncancel` for the old ones and `animationstart`
  * for the new ones.
  */
 
-/**
- * Animation members written in a fixed order rather than generically: the
- * timeline before the range that is measured on it, the rate before the
- * time, and the start time (or, for a paused animation, the current time)
- * last, once the play state is set. `effect` is not
- * replaced, because a CSS animation whose effect script replaces leaves the
- * stylesheet's control; its state is copied onto the new effect instead.
- */
-const ORDERED = new Set([
-  'effect',
-  'timeline',
-  'rangeStart',
-  'rangeEnd',
-  'playbackRate',
-  'startTime',
-  'currentTime',
-]);
-
-type Writable = Record<string, unknown>;
-
-/** Every accessor with a setter on `object`'s prototype chain. */
-function writableAccessors(object: object): string[] {
-  const names = new Set<string>();
-  for (
-    let proto: object | null = Object.getPrototypeOf(object);
-    proto != null && proto !== Object.prototype;
-    proto = Object.getPrototypeOf(proto)
-  ) {
-    for (const [name, descriptor] of Object.entries(
-      Object.getOwnPropertyDescriptors(proto),
-    )) {
-      if (descriptor.set != null) {
-        names.add(name);
-      }
-    }
-  }
-  return [...names];
-}
-
-/**
- * A textual form of a value that is compared by content rather than by
- * identity: a CSS numeric value (as in a timeline range offset) through its
- * serialization, a plain object (a range) through its members. Anything else
- * is compared by identity (`null`).
- */
-function contentOf(value: unknown): string | null {
-  if (
-    typeof CSSNumericValue !== 'undefined' &&
-    value instanceof CSSNumericValue
-  ) {
-    return value.toString();
-  }
-  if (
-    value != null &&
-    typeof value === 'object' &&
-    Object.getPrototypeOf(value) === Object.prototype
-  ) {
-    return Object.entries(value)
-      .map(([key, inner]) => `${key}:${contentOf(inner) ?? String(inner)}`)
-      .join(';');
-  }
-  return null;
-}
-
-function differs(a: unknown, b: unknown): boolean {
-  if (a === b) {
-    return false;
-  }
-  const textA = contentOf(a);
-  return textA == null || textA !== contentOf(b);
-}
-
-interface Saved {
-  animation: Animation;
-  name: string;
-  target: Element | null;
-  pseudoElement: string | null;
-  values: Writable;
-  effectValues: Writable;
-  timing: EffectTiming | null;
-  keyframes: ComputedKeyframe[] | null;
-  playState: AnimationPlayState;
-  replaceState: AnimationReplaceState;
-}
-
-function save(animation: Animation): Saved {
-  const effect = animation.effect as KeyframeEffect | null;
-  const values: Writable = {};
-  for (const name of writableAccessors(animation)) {
-    values[name] = (animation as unknown as Writable)[name];
-  }
-  const effectValues: Writable = {};
-  if (effect != null) {
-    for (const name of writableAccessors(effect)) {
-      effectValues[name] = (effect as unknown as Writable)[name];
-    }
-  }
-  return {
-    animation,
-    name:
-      (animation as Animation & {animationName?: string}).animationName ?? '',
-    target: effect?.target ?? null,
-    pseudoElement: effect?.pseudoElement ?? null,
-    values,
-    effectValues,
-    timing: effect?.getTiming() ?? null,
-    keyframes: effect?.getKeyframes() ?? null,
-    playState: animation.playState,
-    replaceState: animation.replaceState,
-  };
-}
-
-function write(object: object, name: string, value: unknown): void {
-  (object as Writable)[name] = value;
-}
-
-/** Give `next` the effect state `saved` had: every writable member. */
-function restoreEffect(next: KeyframeEffect, saved: Saved): void {
-  for (const name of writableAccessors(next)) {
-    if (
-      name in saved.effectValues &&
-      differs(saved.effectValues[name], (next as unknown as Writable)[name])
-    ) {
-      write(next, name, saved.effectValues[name]);
-    }
-  }
-  if (saved.timing != null) {
-    const timing = next.getTiming() as unknown as Writable;
-    const changed: Writable = {};
-    for (const [field, value] of Object.entries(saved.timing)) {
-      if (differs(value, timing[field])) {
-        changed[field] = value;
-      }
-    }
-    if (Object.keys(changed).length > 0) {
-      next.updateTiming(changed);
-    }
-  }
-  if (
-    saved.keyframes != null &&
-    JSON.stringify(saved.keyframes) !== JSON.stringify(next.getKeyframes())
-  ) {
-    next.setKeyframes(saved.keyframes);
-  }
-}
-
-/** Give `next` the state `saved` had, member by member. */
-function restore(next: Animation, saved: Saved): void {
-  const effect = next.effect as KeyframeEffect | null;
-  if (effect != null) {
-    restoreEffect(effect, saved);
-  }
-  const current = next as unknown as Writable;
-  for (const name of ['timeline', 'rangeStart', 'rangeEnd']) {
-    if (name in saved.values && differs(saved.values[name], current[name])) {
-      write(next, name, saved.values[name]);
-    }
-  }
-  for (const name of writableAccessors(next)) {
-    if (
-      !ORDERED.has(name) &&
-      name in saved.values &&
-      differs(saved.values[name], current[name])
-    ) {
-      write(next, name, saved.values[name]);
-    }
-  }
-  if (saved.replaceState === 'persisted' && next.replaceState !== 'persisted') {
-    next.persist();
-  }
-  const rate = saved.values.playbackRate;
-  if (typeof rate === 'number' && rate !== next.playbackRate) {
-    next.playbackRate = rate;
-  }
-  if (saved.playState === 'paused' && next.playState !== 'paused') {
-    next.pause();
-  } else if (saved.playState !== 'paused' && next.playState === 'paused') {
-    next.play();
-  }
-  // A running animation is anchored to its timeline by its start time, which
-  // carries its current time on exactly. A paused one has none and keeps its
-  // current time. A finished one holds its end: finishing it again holds the
-  // same time, though its start time is then counted from now, since script
-  // cannot set a start time and a held time together.
-  const start = saved.values.startTime as CSSNumberish | null | undefined;
-  const time = saved.values.currentTime as CSSNumberish | null | undefined;
-  if (saved.playState === 'finished') {
-    next.finish();
-  } else if (start != null) {
-    next.startTime = start;
-  } else if (time != null) {
-    next.currentTime = time;
-  }
-}
-
-/** Resume a cancelled CSS transition with a script animation in its state. */
-function resumeTransition(saved: Saved): void {
-  if (saved.target == null || saved.keyframes == null) {
-    return;
-  }
-  const replacement = saved.target.animate(saved.keyframes, {
-    pseudoElement: saved.pseudoElement ?? undefined,
-  });
-  restore(replacement, saved);
-}
-
-function isTransition(animation: Animation): boolean {
-  return (
-    typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition
-  );
-}
+import {restoreAnimations, saveAnimation} from '../motion/carryAnimations';
 
 /**
  * Run `reset`, which takes `root` out of rendering and back, and put every
  * CSS animation and transition of `root` and its subtree back in the state it
- * was in before. Recreated animations are matched to the ones they replace by
- * element, pseudo-element and name, in order, and then by name alone (an
- * effect script moved to another element or pseudo-element); a recreated
- * animation with no predecessor (an entry animation that had already played
- * and been dropped) is finished.
+ * was in before.
  */
 export function preserveAnimations(root: Element, reset: () => void): void {
   if (typeof root.getAnimations !== 'function') {
@@ -257,48 +35,7 @@ export function preserveAnimations(root: Element, reset: () => void): void {
     return;
   }
   const before = root.getAnimations({subtree: true});
-  const saved = before.map(save);
+  const saved = before.map(saveAnimation);
   reset();
-  const after = root.getAnimations({subtree: true});
-  const current = new Set(after);
-  const survivors = new Set(before);
-  const cancelled: Saved[] = [];
-  for (const state of saved) {
-    if (current.has(state.animation)) {
-      continue;
-    }
-    if (isTransition(state.animation)) {
-      resumeTransition(state);
-    } else {
-      cancelled.push(state);
-    }
-  }
-  const recreated = after.filter(animation => !survivors.has(animation));
-  const unmatched: Animation[] = [];
-  for (const animation of recreated) {
-    const effect = animation.effect as KeyframeEffect | null;
-    const name =
-      (animation as Animation & {animationName?: string}).animationName ?? '';
-    const index = cancelled.findIndex(
-      state =>
-        state.name === name &&
-        state.target === (effect?.target ?? null) &&
-        state.pseudoElement === (effect?.pseudoElement ?? null),
-    );
-    if (index === -1) {
-      unmatched.push(animation);
-    } else {
-      restore(animation, cancelled.splice(index, 1)[0]);
-    }
-  }
-  for (const animation of unmatched) {
-    const name =
-      (animation as Animation & {animationName?: string}).animationName ?? '';
-    const index = cancelled.findIndex(state => state.name === name);
-    if (index === -1) {
-      animation.finish();
-    } else {
-      restore(animation, cancelled.splice(index, 1)[0]);
-    }
-  }
+  restoreAnimations(root, saved, new Set(before));
 }

package/src/Layer/useBackdropPress.ts

@@ -11,6 +11,7 @@
  */
 
 import {useCallback, useRef, type PointerEvent, type MouseEvent} from 'react';
+import {outsideDismissalCount} from './outsidePress';
 
 export interface BackdropPressHandlers {
   onPointerDownCapture: (event: PointerEvent<HTMLElement>) => void;
@@ -19,6 +20,21 @@ export interface BackdropPressHandlers {
   onClick: (event: MouseEvent<HTMLElement>) => void;
 }
 
+function isPopoverShowing(element: Element): boolean {
+  try {
+    return element.matches(':popover-open');
+  } catch {
+    // jsdom and pre-Popover browsers do not recognize :popover-open.
+    return false;
+  }
+}
+
+function showingAutoPopovers(host: HTMLElement): ReadonlyArray<Element> {
+  return Array.from(
+    host.ownerDocument.querySelectorAll('[popover="auto"], [popover=""]'),
+  ).filter(element => !element.contains(host) && isPopoverShowing(element));
+}
+
 /**
  * A press on a modal layer's backdrop targets the <dialog> root itself. A
  * click there is also what the browser sends when a press starts on one side
@@ -26,6 +42,14 @@ export interface BackdropPressHandlers {
  * ancestor), so a backdrop press dismisses only when its pointer-down and its
  * pointer-up both landed on the backdrop. A cancelled pointer ends the press.
  *
+ * A press that light-dismisses a layer open above the host, such as a menu
+ * open in the dialog, is that layer's: the host stays open, and the next
+ * backdrop press dismisses it, as a second Escape does. The press is the
+ * layer's when it closes one. A `popover="auto"` layer that showed at
+ * pointer-down no longer shows at the click, or a layer counted its close
+ * with noteOutsideDismissal. A layer that hides for another reason, such as a
+ * Tooltip whose trigger lost focus, does not count.
+ *
  * The pointer handlers run in the capture phase. A nested layer, such as a
  * popover open in the dialog, stops its presses at its own root, so a
  * bubble-phase handler here does not see them.
@@ -36,11 +60,20 @@ export function useBackdropPress(
 ): BackdropPressHandlers {
   const startedOnBackdropRef = useRef(false);
   const endedOnBackdropRef = useRef(false);
+  const autoPopoversRef = useRef<ReadonlyArray<Element>>([]);
+  const dismissalCountRef = useRef(0);
 
   const onPointerDownCapture = useCallback(
     (event: PointerEvent<HTMLElement>) => {
-      startedOnBackdropRef.current = event.target === event.currentTarget;
+      const isOnBackdrop = event.target === event.currentTarget;
+      startedOnBackdropRef.current = isOnBackdrop;
       endedOnBackdropRef.current = false;
+      autoPopoversRef.current = isOnBackdrop
+        ? showingAutoPopovers(event.currentTarget)
+        : [];
+      dismissalCountRef.current = outsideDismissalCount(
+        event.currentTarget.ownerDocument,
+      );
     },
     [],
   );
@@ -54,16 +87,23 @@ export function useBackdropPress(
   const onPointerCancelCapture = useCallback(() => {
     startedOnBackdropRef.current = false;
     endedOnBackdropRef.current = false;
+    autoPopoversRef.current = [];
   }, []);
 
   const onClick = useCallback(
     (event: MouseEvent<HTMLElement>) => {
       const pressWasOnBackdrop = endedOnBackdropRef.current;
+      const dismissedALayerAbove =
+        autoPopoversRef.current.some(layer => !isPopoverShowing(layer)) ||
+        outsideDismissalCount(event.currentTarget.ownerDocument) !==
+          dismissalCountRef.current;
       startedOnBackdropRef.current = false;
       endedOnBackdropRef.current = false;
+      autoPopoversRef.current = [];
       if (
         isEnabled &&
         pressWasOnBackdrop &&
+        !dismissedALayerAbove &&
         event.target === event.currentTarget
       ) {
         onBackdropPress();

package/src/Layer/useLayer.tsx

@@ -354,13 +354,15 @@ export interface FixedLayerOptions extends BaseLayerOptions {
 export interface ContextLayerReturn {
   /**
    * Ref to attach to trigger element.
-   * Injects anchorName style for CSS anchor positioning.
+   * While the layer is shown, and until its exit animation ends, the trigger
+   * carries the layer's CSS anchor name.
    */
   ref: RefCallback<HTMLElement>;
 
   /**
    * The CSS anchor name to use for positioning.
    * Use this when you need to set anchorName manually (e.g., display:contents wrapper).
+   * Set it only while the layer is shown or its exit animation runs.
    */
   anchorId: string;
 
@@ -547,6 +549,24 @@ function untransform(
   return new DOMRect(left, top, width, height);
 }
 
+/**
+ * The finite animations still running on `layer` and its content. A layer
+ * that fades out keeps running them after the browser hides it, and it stays
+ * placed against its anchor until they end.
+ */
+function exitAnimations(layer: HTMLElement | null): Animation[] {
+  if (layer == null || typeof layer.getAnimations !== 'function') {
+    return [];
+  }
+  return layer
+    .getAnimations({subtree: true})
+    .filter(
+      animation =>
+        animation.playState === 'running' &&
+        animation.effect?.getComputedTiming().endTime !== Infinity,
+    );
+}
+
 /**
  * The layer's box where its position option put it, without the transform an
  * entry animation (or anything else) applies to it: a Tooltip enters from a
@@ -1216,6 +1236,41 @@ function useLayerImplementation(
   // stale-closure reads of the previous isOpen value.
   const isOpenRef = useRef(false);
 
+  // The exit of the layer that closed last, while it still paints. Its
+  // trigger stays an anchor until it ends, also when the trigger attaches
+  // again during it. Null once it has ended.
+  const exitRef = useRef<object | null>(null);
+
+  // A closed trigger is no anchor, once the layer stops painting. A show
+  // during the exit keeps the name, and so does a later exit.
+  const releaseAnchor = useCallback(
+    (layer: HTMLElement | null) => {
+      const exit = {};
+      exitRef.current = exit;
+      const release = () => {
+        if (exitRef.current !== exit) {
+          return;
+        }
+        exitRef.current = null;
+        const trigger = triggerRef.current;
+        if (!isOpenRef.current && trigger != null) {
+          removeAnchorName(trigger, anchorId);
+        }
+      };
+      const running = exitAnimations(layer);
+      if (running.length === 0) {
+        release();
+        return;
+      }
+      void Promise.all(
+        running.map(async animation =>
+          animation.finished.catch(() => undefined),
+        ),
+      ).then(release);
+    },
+    [anchorId],
+  );
+
   // The gesture during which the browser last closed this layer on its own.
   // Read through wasJustDismissed by triggers deciding whether a click is
   // theirs to act on.
@@ -1416,6 +1471,12 @@ function useLayerImplementation(
       popover.removeAttribute(LAYER_CLEARS_ANCHOR_ATTRIBUTE);
       popover.removeAttribute(LAYER_SCROLLS_ATTRIBUTE);
       applyDeferredWritingContext(popover);
+      // The trigger takes the layer's anchor name in the task that shows the
+      // layer, so the layer's first frame is placed against it.
+      const anchor = triggerRef.current;
+      if (anchor != null) {
+        addAnchorName(anchor, anchorId);
+      }
       // A hide the browser runs itself (an Escape its close watcher answers)
       // is counted too, from `beforetoggle` until the element's `toggle`, a
       // task after the hide has returned. The show is asked of the browser
@@ -1423,6 +1484,11 @@ function useLayerImplementation(
       // light dismiss at pointerup, then this show at the click); only a show
       // it refuses replays once the hide's count has ended.
       if (!showPopoverElement(popover)) {
+        // The replay anchors the trigger again; until then it is closed. An
+        // exit still running keeps the name.
+        if (anchor != null && exitRef.current == null) {
+          removeAnchorName(anchor, anchorId);
+        }
         replayWhenSettled();
         return;
       }
@@ -1434,6 +1500,7 @@ function useLayerImplementation(
       onShow?.();
     }
   }, [
+    anchorId,
     onShow,
     keepsAnchorClear,
     requestContextMount,
@@ -1470,8 +1537,9 @@ function useLayerImplementation(
       setIsOpen(false);
       onHide?.();
     }
+    releaseAnchor(popoverRef.current);
     clearContextMount();
-  }, [onHide, clearContextMount]);
+  }, [onHide, clearContextMount, releaseAnchor]);
 
   // A deferred show() replays through a ref so the queued closure reaches the
   // current callback rather than the one captured when it was queued.
@@ -1493,7 +1561,11 @@ function useLayerImplementation(
         removeAnchorName(triggerRef.current, anchorId);
       }
 
-      if (el) {
+      // Only a shown layer's trigger is an anchor. WebKit's Linux ports run the
+      // transform animation of an element that holds an anchor on the main
+      // thread. A busy task would then freeze a surface that moves around a
+      // closed trigger.
+      if (el && (isOpenRef.current || exitRef.current != null)) {
         addAnchorName(el, anchorId);
       }
 
@@ -1603,12 +1675,13 @@ function useLayerImplementation(
         rememberDismissal(
           (e.currentTarget as HTMLElement | null)?.ownerDocument ?? document,
         );
+        releaseAnchor(e.currentTarget as HTMLElement | null);
         setIsOpen(false);
         onHide?.();
         clearContextMount();
       }
     },
-    [onHide, clearContextMount, rememberDismissal],
+    [onHide, clearContextMount, rememberDismissal, releaseAnchor],
   );
 
   // Ref callback for popover element — sets up the `toggle` listener.

package/src/Layer/useTouchTrigger.ts

@@ -53,6 +53,7 @@ import {
   type RefObject,
 } from 'react';
 import {currentGesture} from './gestureCounter';
+import {noteOutsideDismissal} from './outsidePress';
 import {
   innermostInteractive,
   matchesInteractiveSelectors,
@@ -436,6 +437,9 @@ export function useTouchTriggerInternal(
         }
       }
       disarmOutsideDismiss();
+      if (target != null) {
+        noteOutsideDismissal(target.ownerDocument ?? document);
+      }
       hideRef.current();
     };
 

package/src/Layout/LayoutContent.doc.mjs

@@ -30,7 +30,8 @@ export const docs = {
     {
       name: 'label',
       type: 'string',
-      description: 'Accessible label for the landmark element.',
+      description:
+        'Accessible label for the landmark element. While the region scrolls, it also names the scrolling region, which otherwise takes a translated "Content".',
     },
     {
       name: 'role',
@@ -66,7 +67,8 @@ export const docsZh = {
     {
       name: 'label',
       type: 'string',
-      description: '地标元素的无障碍标签。',
+      description:
+        '地标元素的无障碍标签。区域滚动时，它也为滚动区域命名；未提供时使用已翻译的“Content”（内容）。',
     },
     {
       name: 'role',
@@ -86,7 +88,8 @@ export const docsDense = {
     padding: 'Internal padding on spacing scale. Overrides layout container default.',
     isScrollable:
       'Enable scrollable overflow. With arithmetic contentWidth values, the scrollport reaches open sides while context-aware insets align children.',
-    label: 'Accessible label for landmark element.',
+    label:
+      'Accessible label for landmark element; also names the region while it scrolls (default "Content").',
     role: 'ARIA landmark role.',
   },
 };

package/src/Layout/LayoutContent.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file LayoutContent.tsx
- * @input Uses React StyleX, LayoutSlotsContext
+ * @input Uses React StyleX, LayoutSlotsContext, useScrollRegionProps
  * @output Exports LayoutContent component and LayoutContentProps
  * @position Scrollable main content area for Layout. Wraps the primary body content
  *   with automatic scroll containment and context-aware padding.
@@ -21,6 +21,8 @@ import {use} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import {LayoutSlotsContext} from './LayoutSlotsContext';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useScrollRegionProps} from '../hooks/useScrollRegionProps';
 import {mergeProps} from '../utils/mergeProps';
 import type {SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
@@ -132,6 +134,8 @@ export interface LayoutContentProps extends BaseProps<HTMLDivElement> {
   /**
    * Accessible label for the landmark.
    * Required when role is set and multiple landmarks of the same type exist.
+   * While the content scrolls, it also names the scrolling region, which
+   * otherwise takes a translated "Content".
    */
   label?: string;
 
@@ -192,12 +196,14 @@ export function LayoutContent({
   const {hasHeader, hasFooter, hasStart, hasEnd} = use(LayoutSlotsContext);
 
   const isZeroPadding = padding === 0;
+  const region = useScrollRegionProps({isScrollable, role, label});
+  const mergedRef = useMergedRefs(ref, region.ref);
 
   return (
     <div
-      ref={ref}
-      role={role}
-      aria-label={label}
+      ref={mergedRef}
+      role={region.role}
+      aria-label={region['aria-label']}
       {...mergeProps(
         themeProps('layout-content'),
         stylex.props(