Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

chore(core): name the system that 88 kept Effects sync (#9787)

Cindy Zhang9889a3438652
diff --git a/.changeset/core-effect-sync-notes.md b/.changeset/core-effect-sync-notes.md
new file mode 100644
index 0000000000..da527a0539
--- /dev/null
+++ b/.changeset/core-effect-sync-notes.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[docs] Source comments above 88 kept Effects in Core now name the external system each one syncs. Nothing a consumer imports or renders changes.
+
+@cixzhang
diff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsx
index 313d3fa2b9..6df6901823 100644
--- a/packages/core/src/AppShell/AppShell.tsx
+++ b/packages/core/src/AppShell/AppShell.tsx
@@ -647,6 +647,8 @@ export function AppShell({
if (isMobileNavOpen && !isMobileNavCloseHeld) {
setIsMobileNavCloseHeld(true);
}
+ // Syncs the mobile-nav close hold with a timer. The hold ends after the
+ // slide-out delay.
useEffect(() => {
if (!HasActivity || isMobileNavOpen) {
return;
@@ -814,6 +816,8 @@ export function AppShell({
const headerRef = useRef<HTMLDivElement>(null);
const shellRef = useRef<HTMLDivElement>(null);
+ // Syncs the header-height CSS variable with a ResizeObserver while the height
+ // is automatic.
useEffect(() => {
if (!isAuto || !headerRef.current || !shellRef.current) {
return;
diff --git a/packages/core/src/BottomSheet/BottomSheet.tsx b/packages/core/src/BottomSheet/BottomSheet.tsx
index 01355e7fe2..cdadbdc113 100644
--- a/packages/core/src/BottomSheet/BottomSheet.tsx
+++ b/packages/core/src/BottomSheet/BottomSheet.tsx
@@ -517,6 +517,7 @@ function StandaloneBottomSheet({
const stackViewRef = useRef(stackView);
stackViewRef.current = stackView;
const scrimWriteRef = useRef<BottomSheetScrimWrite>({frame: null});
+ // Releases the pending scrim write frame on unmount.
useEffect(() => () => cancelScrimWrite(scrimWriteRef.current), []);
const writeScrim = useCallback(
(opacity: '0' | '1') =>
diff --git a/packages/core/src/BottomSheet/BottomSheetPanel.tsx b/packages/core/src/BottomSheet/BottomSheetPanel.tsx
index 770bfb9457..031f6fa498 100644
--- a/packages/core/src/BottomSheet/BottomSheetPanel.tsx
+++ b/packages/core/src/BottomSheet/BottomSheetPanel.tsx
@@ -710,6 +710,8 @@ export function BottomSheetPanel({
const isCoarseCrossFade = useMediaQuery(REDUCED_MOTION_COARSE_QUERY);
const isCrossFade =
isCoarseCrossFade || (isReducedMotion && isDismissedByTouchDrag);
+ // Syncs the motion with the panel's CSS transition. The motion completes when
+ // that transition ends.
useLayoutEffect(() => {
if (motion == null) {
return;
diff --git a/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx b/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
index 778894e61a..3abb91f987 100644
--- a/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
+++ b/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
@@ -358,6 +358,7 @@ export function BottomSheetSwitcher({
const stackViewRef = useRef(stackView);
stackViewRef.current = stackView;
const scrimWriteRef = useRef<BottomSheetScrimWrite>({frame: null});
+ // Releases the pending scrim write frame on unmount.
useEffect(() => () => cancelScrimWrite(scrimWriteRef.current), []);
// What the flow's place in the stack was when it left the registry: its
// depth and the open sheet beneath it. React runs the registration
@@ -564,6 +565,9 @@ export function BottomSheetSwitcher({
presentationCounterRef.current += 1;
presentationOrderRef.current.set(sheetId, presentationCounterRef.current);
}, []);
+ // Syncs document focus with the flow's visibility. When the flow hides, focus
+ // goes to the opener, to the sheet now on top, or to the target of the
+ // registry.
useLayoutEffect(() => {
if (isFlowVisible) {
if (!hasScrim) {
@@ -694,6 +698,7 @@ export function BottomSheetSwitcher({
unregister();
};
}, [hasScrim, isFlowVisible, onBeforeSheetPresent]);
+ // Syncs the open state of this flow in the sheet stack registry.
useLayoutEffect(() => {
if (isFlowVisible && hasScrim) {
setBottomSheetOpen(stackKeyRef.current, isFlowOpen);
diff --git a/packages/core/src/BottomSheet/useMobileKeyboard.ts b/packages/core/src/BottomSheet/useMobileKeyboard.ts
index b1e74ab665..55ea68e888 100644
--- a/packages/core/src/BottomSheet/useMobileKeyboard.ts
+++ b/packages/core/src/BottomSheet/useMobileKeyboard.ts
@@ -148,6 +148,8 @@ export function useMobileKeyboard({
}
}, [isEnabled, isSheetTraveling, sheetRef]);
+ // Syncs the on-screen keyboard with the sheet. When a presented sheet closes,
+ // the focused field blurs, so the keyboard closes.
useEffect(() => {
if (!isEnabled || !isPresented || isOpen) {
return;
@@ -165,6 +167,8 @@ export function useMobileKeyboard({
}
}, [isEnabled, isOpen, isPresented, sheetRef]);
+ // Syncs the body's end inset with the visual viewport, so the on-screen
+ // keyboard does not cover the body.
useEffect(() => {
const body = bodyRef.current;
const sheet = sheetRef.current;
diff --git a/packages/core/src/BottomSheet/useSheetGestures.ts b/packages/core/src/BottomSheet/useSheetGestures.ts
index c49fb9a465..f6422da62f 100644
--- a/packages/core/src/BottomSheet/useSheetGestures.ts
+++ b/packages/core/src/BottomSheet/useSheetGestures.ts
@@ -699,6 +699,8 @@ export function useSheetGestures({
const sheetElRef = useRef<HTMLElement | null>(null);
const bodyNodeRef = useRef<HTMLElement | null>(null);
const observerRef = useRef<ResizeObserver | null>(null);
+ // Syncs the browser layout with the transform reset, then ends the
+ // scroll-area reconcile one frame later.
useLayoutEffect(() => {
if (!isScrollAreaReconciling) {
return;
@@ -758,6 +760,7 @@ export function useSheetGestures({
},
[recordSheetHeight],
);
+ // Releases the height observer on unmount.
useEffect(() => () => observerRef.current?.disconnect(), []);
// Reset to the tallest detent each time the sheet re-opens.
@@ -909,6 +912,8 @@ export function useSheetGestures({
resolveDetents,
]);
+ // Syncs window resize and orientation listeners with `isOpen`. Each event
+ // anchors the sheet to its settled detent again.
useEffect(() => {
if (!isOpen || typeof window === 'undefined') {
return;
@@ -1026,6 +1031,8 @@ export function useSheetGestures({
[prepareScrollAreaSettle, resolveDetents],
);
+ // Syncs window blur and document visibilitychange listeners with `isOpen`. A
+ // blur or a hidden page cancels a drag.
useEffect(() => {
// Only an open sheet can be dragged; a closed one listens to nothing.
if (!isOpen) {
diff --git a/packages/core/src/Carousel/Carousel.tsx b/packages/core/src/Carousel/Carousel.tsx
index 8f04f0b560..8ba62b7c49 100644
--- a/packages/core/src/Carousel/Carousel.tsx
+++ b/packages/core/src/Carousel/Carousel.tsx
@@ -369,6 +369,7 @@ export function Carousel({
lightDismiss: false,
});
+ // Syncs the layer with `hasButtons`.
useEffect(() => {
if (hasButtons) {
layer.show();
diff --git a/packages/core/src/Chat/ChatComposerInput.tsx b/packages/core/src/Chat/ChatComposerInput.tsx
index d6ba55e33b..603c53011a 100644
--- a/packages/core/src/Chat/ChatComposerInput.tsx
+++ b/packages/core/src/Chat/ChatComposerInput.tsx
@@ -529,6 +529,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
};
}, [inputControlRef, focusEditableAtEnd]);
+ // Syncs the contentEditable DOM with the controlled `value`.
useEffect(() => {
if (controlledValue === undefined || !editableRef.current) {
return;
@@ -650,6 +651,7 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
}
: triggerMenu.ariaProps;
+ // Syncs the trigger menu's pending searches with `isDisabled`.
useEffect(() => {
if (isDisabled && triggerMenu.state.isActive) {
// Reset also cancels pending searches, so late results cannot reopen
diff --git a/packages/core/src/Chat/ChatMessageList.tsx b/packages/core/src/Chat/ChatMessageList.tsx
index a160762849..a13a3b82a3 100644
--- a/packages/core/src/Chat/ChatMessageList.tsx
+++ b/packages/core/src/Chat/ChatMessageList.tsx
@@ -265,7 +265,8 @@ export function ChatMessageList({
children !== false &&
!(Array.isArray(children) && children.length === 0);
- // IntersectionObserver for scroll-to-top infinite scroll
+ // Syncs an IntersectionObserver on the top sentinel with `scrollToTopAction`.
+ // The action runs when the sentinel comes into view.
useEffect(() => {
const scrollContainer = layoutContext?.scrollContainerRef?.current;
if (!scrollToTopAction || !sentinelRef.current) {
diff --git a/packages/core/src/Chat/useChatDictation.ts b/packages/core/src/Chat/useChatDictation.ts
index 3384d2f8e6..42cc0a10dd 100644
--- a/packages/core/src/Chat/useChatDictation.ts
+++ b/packages/core/src/Chat/useChatDictation.ts
@@ -395,6 +395,7 @@ export function useChatDictation(
[userTransform],
);
+ // Releases the audio analyser and the animation frame on unmount.
useEffect(() => {
return () => {
analyserRef.current?.cleanup();
diff --git a/packages/core/src/Chat/useChatNewMessages.ts b/packages/core/src/Chat/useChatNewMessages.ts
index fe5c734022..b175989f5f 100644
--- a/packages/core/src/Chat/useChatNewMessages.ts
+++ b/packages/core/src/Chat/useChatNewMessages.ts
@@ -121,7 +121,7 @@ export function useChatNewMessages({
[attach, detach],
);
- // Cleanup on unmount
+ // Releases the new-message tracking on unmount.
useEffect(() => {
return () => detach();
}, [detach]);
diff --git a/packages/core/src/Chat/useChatStreamScroll.ts b/packages/core/src/Chat/useChatStreamScroll.ts
index 1b1204058c..915e5ce8f7 100644
--- a/packages/core/src/Chat/useChatStreamScroll.ts
+++ b/packages/core/src/Chat/useChatStreamScroll.ts
@@ -358,6 +358,8 @@ export function useChatStreamScroll({
// --- Event listeners ---
+ // Syncs scroll and scrollend listeners on the stream container with
+ // `enabled`.
useEffect(() => {
const el = scrollRef.current;
if (!el || !enabled) {
diff --git a/packages/core/src/Chat/useSpeechRecognition.ts b/packages/core/src/Chat/useSpeechRecognition.ts
index 741588d05f..4b95101973 100644
--- a/packages/core/src/Chat/useSpeechRecognition.ts
+++ b/packages/core/src/Chat/useSpeechRecognition.ts
@@ -317,6 +317,8 @@ export function useSpeechRecognition(
transformTranscript,
};
+ // Releases speech recognition, the audio analyser and the animation frame on
+ // unmount.
useEffect(() => {
return () => {
recognitionRef.current?.abort();
diff --git a/packages/core/src/Chat/useTriggerMenu.tsx b/packages/core/src/Chat/useTriggerMenu.tsx
index 45a1a95b15..866257effb 100644
--- a/packages/core/src/Chat/useTriggerMenu.tsx
+++ b/packages/core/src/Chat/useTriggerMenu.tsx
@@ -452,7 +452,7 @@ export function useTriggerMenu(
});
const {show: showPopover, hide: hidePopover} = popover;
- // Cleanup on unmount
+ // Releases the search timer and the anchor span on unmount.
useEffect(() => {
return () => {
if (searchTimeoutRef.current) {
diff --git a/packages/core/src/CodeBlock/CodeBlock.tsx b/packages/core/src/CodeBlock/CodeBlock.tsx
index cca7c43123..36644d4397 100644
--- a/packages/core/src/CodeBlock/CodeBlock.tsx
+++ b/packages/core/src/CodeBlock/CodeBlock.tsx
@@ -821,6 +821,8 @@ function SpanCodeContent({
maxDigits: number;
startLineNumber: number;
}) {
+ // Syncs the document's ::highlight() stylesheet. The rules go in one time,
+ // before layout reads.
useInsertionEffect(() => {
ensureHighlightStyles();
}, []);
@@ -923,6 +925,8 @@ function RangeCodeContent({
}
}, []);
+ // Syncs the CSS.highlights registry with the token ranges. It applies them in
+ // chunks.
useEffect(() => {
if (!hasHighlightAPI()) {
return;
diff --git a/packages/core/src/CommandPalette/CommandPalette.tsx b/packages/core/src/CommandPalette/CommandPalette.tsx
index e1dbcc3e90..da524a2bc6 100644
--- a/packages/core/src/CommandPalette/CommandPalette.tsx
+++ b/packages/core/src/CommandPalette/CommandPalette.tsx
@@ -509,6 +509,7 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
const runSearchRef = useRef(runSearch);
runSearchRef.current = runSearch;
+ // Syncs the search source with `isOpen`. An open runs the empty-query search.
useEffect(() => {
if (isOpen) {
runSearchRef.current('');
diff --git a/packages/core/src/CommandPalette/CommandPaletteItem.tsx b/packages/core/src/CommandPalette/CommandPaletteItem.tsx
index cac88d5d83..1f8fb6e8d8 100644
--- a/packages/core/src/CommandPalette/CommandPaletteItem.tsx
+++ b/packages/core/src/CommandPalette/CommandPaletteItem.tsx
@@ -155,6 +155,7 @@ export function CommandPaletteItem({
(ctx ? ctx.highlightedIndex === itemIndex && itemIndex >= 0 : false);
const isSelected = controlledSelected ?? (ctx ? ctx.value === value : false);
+ // Syncs the scroll position of a standalone item with `isHighlighted`.
useEffect(() => {
// Inside CommandPalette the shared useHighlightedOptionScroll (via
// useCombobox) is the single scrollIntoView owner (#6077); a second owner
diff --git a/packages/core/src/DateInput/MonthScroller.tsx b/packages/core/src/DateInput/MonthScroller.tsx
index 43d63b5035..376804946d 100644
--- a/packages/core/src/DateInput/MonthScroller.tsx
+++ b/packages/core/src/DateInput/MonthScroller.tsx
@@ -594,6 +594,7 @@ export function MonthScroller({
* it cannot oscillate.
*/
const settleFrameRef = useRef<number | undefined>(undefined);
+ // Releases the settle frame on unmount.
useEffect(
() => () => {
if (settleFrameRef.current != null) {
@@ -666,6 +667,8 @@ export function MonthScroller({
// rAF-throttled: a touch scroll fires far more scroll events than frames,
// and all this does is move a label and widen a window.
const frameRef = useRef<number | undefined>(undefined);
+ // Syncs scroll, touch and wheel listeners on the scroller with its measured
+ // height.
useEffect(() => {
const scroller = scrollerRef.current;
// Not before the height is known. A listener attached while it was zero
diff --git a/packages/core/src/DateInput/TouchDateField.tsx b/packages/core/src/DateInput/TouchDateField.tsx
index 772b6c92c3..d70e38935e 100644
--- a/packages/core/src/DateInput/TouchDateField.tsx
+++ b/packages/core/src/DateInput/TouchDateField.tsx
@@ -676,6 +676,7 @@ export function TouchDateField({
const scrollerHandleRef = useRef<MonthScrollerHandle | null>(null);
// Pending focus handoff from the clear button; see handleClear.
const clearFocusTimerRef = useRef<number | null>(null);
+ // Releases the focus timer on unmount.
useEffect(
() => () => {
if (clearFocusTimerRef.current != null) {
diff --git a/packages/core/src/DateInput/Wheel.tsx b/packages/core/src/DateInput/Wheel.tsx
index 2fafc9ba63..5c8e6e62ce 100644
--- a/packages/core/src/DateInput/Wheel.tsx
+++ b/packages/core/src/DateInput/Wheel.tsx
@@ -462,6 +462,8 @@ export function Wheel({
// useScrollSettle. The settle handler re-checks the position afterwards, so
// a correction that is genuinely needed still happens, just at rest.
const parkedRef = useRef(false);
+ // Syncs the wheel's scroll position with the selected index while the wheel
+ // is active.
useEffect(() => {
if (!isActive) {
parkedRef.current = false;
@@ -492,6 +494,8 @@ export function Wheel({
// Highlight follows the finger. rAF-throttled: a scroll can fire far more
// often than the display refreshes, and this only feeds a repaint.
const frameRef = useRef<number | undefined>(undefined);
+ // Syncs a scroll listener with the active wheel. It updates the highlighted
+ // row.
useEffect(() => {
const scroller = scrollerRef.current;
if (scroller == null || !isActive) {
diff --git a/packages/core/src/DateInput/useOwnScrollGesture.ts b/packages/core/src/DateInput/useOwnScrollGesture.ts
index ad5b5d0823..c25870dbb7 100644
--- a/packages/core/src/DateInput/useOwnScrollGesture.ts
+++ b/packages/core/src/DateInput/useOwnScrollGesture.ts
@@ -137,6 +137,8 @@ export function useOwnScrollGesture(
const onSwipeRef = useRef(onSwipe);
onSwipeRef.current = onSwipe;
+ // Syncs touch listeners on the element with `isEnabled`. They decide which
+ // gesture owns a horizontal scroll.
useEffect(() => {
const element = ref.current;
if (element == null || !isEnabled) {
diff --git a/packages/core/src/DateInput/usePointerDragScroll.ts b/packages/core/src/DateInput/usePointerDragScroll.ts
index 6f937ed6b3..98613751bb 100644
--- a/packages/core/src/DateInput/usePointerDragScroll.ts
+++ b/packages/core/src/DateInput/usePointerDragScroll.ts
@@ -87,6 +87,7 @@ export function usePointerDragScroll(
): PointerDragScrollState {
const isDraggingRef = useRef(false);
+ // Syncs pointer listeners with `isEnabled`. A mouse drag scrolls the element.
useEffect(() => {
const element = ref.current;
if (element == null || !isEnabled) {
diff --git a/packages/core/src/DateInput/useScrollSettle.ts b/packages/core/src/DateInput/useScrollSettle.ts
index 2deb897ddc..e5ff8642de 100644
--- a/packages/core/src/DateInput/useScrollSettle.ts
+++ b/packages/core/src/DateInput/useScrollSettle.ts
@@ -98,6 +98,8 @@ export function useScrollSettle(
const isAtRestRef = useRef(true);
+ // Syncs scroll, touch and pointer listeners with `isEnabled`. They find when
+ // scrolling stops.
useEffect(() => {
const element = ref.current;
if (element == null || !isEnabled) {
diff --git a/packages/core/src/Dialog/Dialog.tsx b/packages/core/src/Dialog/Dialog.tsx
index ebe3105173..a97d4d56b3 100644
--- a/packages/core/src/Dialog/Dialog.tsx
+++ b/packages/core/src/Dialog/Dialog.tsx
@@ -606,7 +606,8 @@ export function Dialog({
const allowEscape = purpose !== 'required';
const allowBackdropClick = purpose === 'info';
- // Handle open/close state — skip for inline rendering
+ // Syncs the native dialog with `isOpen` through `showModal()` and `close()`.
+ // An inline dialog is not in the top layer, so it skips this.
useEffect(() => {
if (isInline) {
return;
diff --git a/packages/core/src/Drawer/useDrawerDialogPresence.ts b/packages/core/src/Drawer/useDrawerDialogPresence.ts
index 673bff98e1..7279429c89 100644
--- a/packages/core/src/Drawer/useDrawerDialogPresence.ts
+++ b/packages/core/src/Drawer/useDrawerDialogPresence.ts
@@ -131,6 +131,8 @@ export function useDrawerDialogPresence({
// Element focused when the drawer opened — restored on close.
const triggerElementRef = useRef<HTMLElement | null>(null);
+ // Syncs the drawer's native host with `isOpen`. It shows or hides the
+ // top-layer host, keeps the opener, waits for the exit, and returns focus.
useEffect(() => {
const dialog = dialogRef.current;
if (!dialog) {
diff --git a/packages/core/src/DropdownMenu/useMenuOverflow.ts b/packages/core/src/DropdownMenu/useMenuOverflow.ts
index ed1b72a881..999287e027 100644
--- a/packages/core/src/DropdownMenu/useMenuOverflow.ts
+++ b/packages/core/src/DropdownMenu/useMenuOverflow.ts
@@ -63,6 +63,8 @@ export function useMenuOverflow(
);
}, [menuRef]);
+ // Syncs the overflow measurement with the open menu. It measures, then
+ // observes resize, DOM changes and window resize.
useIsomorphicLayoutEffect(() => {
if (!isOpen) {
return;
@@ -98,6 +100,7 @@ export function useMenuOverflow(
};
}, [isOpen, measureOverflow, menuRef]);
+ // Measures overflow again after the content changes while the menu is open.
useIsomorphicLayoutEffect(() => {
if (isOpen) {
measureOverflow();
diff --git a/packages/core/src/FieldStatus/useFieldStatusAnnouncement.ts b/packages/core/src/FieldStatus/useFieldStatusAnnouncement.ts
index 884957326e..ff612e4daa 100644
--- a/packages/core/src/FieldStatus/useFieldStatusAnnouncement.ts
+++ b/packages/core/src/FieldStatus/useFieldStatusAnnouncement.ts
@@ -36,6 +36,7 @@ export function useFieldStatusAnnouncement(
type: InputStatusType | undefined,
): void {
const announce = useAnnounce();
+ // Syncs the live region with the status message.
useEffect(() => {
if (message) {
announce(message, type === 'error' ? 'assertive' : 'polite');
diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsx
index 4dbe602f57..7682d70e2d 100644
--- a/packages/core/src/HoverCard/useHoverCard.tsx
+++ b/packages/core/src/HoverCard/useHoverCard.tsx
@@ -585,7 +585,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
[layerRef, interactionRef],
);
- // Cleanup on unmount
+ // Releases the hover-card timers on unmount.
useEffect(() => {
return () => {
clearTimeouts();
@@ -600,7 +600,8 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
// eslint-disable-next-line @eslint-react/exhaustive-deps -- intentionally only on mount
}, []);
- // Controlled open state — overrides hover/focus triggers
+ // Syncs the layer with the controlled `isOpen`. A close moves focus back to
+ // the trigger when the card holds it.
useEffect(() => {
if (isOpen === undefined) {
return;
diff --git a/packages/core/src/Item/useSwipeAction.ts b/packages/core/src/Item/useSwipeAction.ts
index 7234a2e9e2..d3e979d78e 100644
--- a/packages/core/src/Item/useSwipeAction.ts
+++ b/packages/core/src/Item/useSwipeAction.ts
@@ -237,6 +237,8 @@ export function useSwipeAction({
reducedMotionRef.current = isReducedMotion;
});
+ // Releases the settle timer, the animation frame and the pinch watch on
+ // unmount.
useEffect(
() => () => {
if (settleTimerRef.current != null) {
diff --git a/packages/core/src/Layer/modalOutlet.ts b/packages/core/src/Layer/modalOutlet.ts
index dee9fd3090..c68a538d0e 100644
--- a/packages/core/src/Layer/modalOutlet.ts
+++ b/packages/core/src/Layer/modalOutlet.ts
@@ -188,6 +188,8 @@ export function useModalOutlet(
const isLatestRef = useRef(isLatest);
isLatestRef.current = isLatest;
const suppliedRef = useRef<HTMLDialogElement | null>(null);
+ // Syncs the module registry of modal outlets with this dialog while it is
+ // active. It also follows the dialog's native `close` event.
useEffect(() => {
const element = ref.current;
if (!isActive || element == null) {
diff --git a/packages/core/src/Layer/outsidePress.ts b/packages/core/src/Layer/outsidePress.ts
index b8e9ccf6b1..d910936de1 100644
--- a/packages/core/src/Layer/outsidePress.ts
+++ b/packages/core/src/Layer/outsidePress.ts
@@ -96,6 +96,7 @@ export function useOutsidePress(): OutsidePressWatch {
},
[],
);
+ // Stops the outside-press listeners on unmount.
useEffect(() => stop, [stop]);
return useMemo(() => ({start, stop}), [start, stop]);
}
diff --git a/packages/core/src/Layer/useLayer.tsx b/packages/core/src/Layer/useLayer.tsx
index d25c2f73a8..5460b87ad5 100644
--- a/packages/core/src/Layer/useLayer.tsx
+++ b/packages/core/src/Layer/useLayer.tsx
@@ -1560,6 +1560,8 @@ function useLayerImplementation(
forgetDismissalRef.current = forget;
}, []);
+ // Syncs the document's capture-phase gesture tracking with this mount.
+ // Unmount forgets the layer's dismissal.
useEffect(() => {
// Install capture-phase gesture tracking before the first interaction.
currentGesture();
diff --git a/packages/core/src/Layer/useLayerDismissal.ts b/packages/core/src/Layer/useLayerDismissal.ts
index 0168ef100d..31279fc388 100644
--- a/packages/core/src/Layer/useLayerDismissal.ts
+++ b/packages/core/src/Layer/useLayerDismissal.ts
@@ -155,6 +155,8 @@ export function useLayerDismissal(
const isRegistered = isActive && isEnabled;
+ // Syncs the shared dismissal stack with `isRegistered`. A registered layer
+ // gets Escape and outside presses in stack order.
useEffect(() => {
if (!isRegistered) {
wasRegisteredRef.current = false;
diff --git a/packages/core/src/Layer/useTouchTrigger.ts b/packages/core/src/Layer/useTouchTrigger.ts
index 2136464f79..85bade346b 100644
--- a/packages/core/src/Layer/useTouchTrigger.ts
+++ b/packages/core/src/Layer/useTouchTrigger.ts
@@ -436,7 +436,9 @@ export function useTouchTriggerInternal(
}
}, [triggerRef, disarmOutsideDismiss]);
+ // Releases the outside-dismiss listener on unmount.
useEffect(() => disarmOutsideDismiss, [disarmOutsideDismiss]);
+ // Releases a pending tap on unmount.
useEffect(() => () => forgetPendingTapRef.current?.(), []);
const isTouchInteraction = useCallback(
diff --git a/packages/core/src/Lightbox/Lightbox.tsx b/packages/core/src/Lightbox/Lightbox.tsx
index 4ba7244cf7..144d032b96 100644
--- a/packages/core/src/Lightbox/Lightbox.tsx
+++ b/packages/core/src/Lightbox/Lightbox.tsx
@@ -429,6 +429,7 @@ export function Lightbox({
// Open/close dialog. The dialog renders only with an item, so a viewer
// opened before its first item arrives opens when that item does.
const hasItem = currentItem != null;
+ // Syncs the native dialog with `isOpen` through `showModal()` and `close()`.
useIsomorphicLayoutEffect(() => {
const dialog = dialogRef.current;
if (!dialog || !hasItem) {
diff --git a/packages/core/src/Outline/useOutlineFromDOM.ts b/packages/core/src/Outline/useOutlineFromDOM.ts
index 1b24c8cad7..9afbf7f740 100644
--- a/packages/core/src/Outline/useOutlineFromDOM.ts
+++ b/packages/core/src/Outline/useOutlineFromDOM.ts
@@ -42,6 +42,8 @@ export function useOutlineFromDOM(
collectOutlineItems(containerRef.current),
);
+ // Syncs the outline items with the container's DOM through a
+ // MutationObserver.
useEffect(() => {
const container = containerRef.current;
setItems(collectOutlineItems(container));
diff --git a/packages/core/src/Outline/useScrollSpy.ts b/packages/core/src/Outline/useScrollSpy.ts
index bb8606f28a..2144542215 100644
--- a/packages/core/src/Outline/useScrollSpy.ts
+++ b/packages/core/src/Outline/useScrollSpy.ts
@@ -275,6 +275,8 @@ export function useScrollSpy({
);
}, [rootRef, scrollContainerRef]);
+ // Syncs a scroll listener on the scroll root and a window resize listener
+ // with the items and offset. They choose the active outline item.
useEffect(() => {
if (isControlled || typeof window === 'undefined') {
return;
diff --git a/packages/core/src/OverflowList/OverflowList.tsx b/packages/core/src/OverflowList/OverflowList.tsx
index b277855df4..fed9a652dc 100644
--- a/packages/core/src/OverflowList/OverflowList.tsx
+++ b/packages/core/src/OverflowList/OverflowList.tsx
@@ -350,6 +350,8 @@ export function OverflowList({
const overflowItemsRef = useRef(overflowItems);
overflowItemsRef.current = overflowItems;
+ // Reports the measured overflow to `onOverflowChange`. A ResizeObserver
+ // drives the measurement, so no event handler can report it.
useIsomorphicLayoutEffect(() => {
if (
!onOverflowChange ||
diff --git a/packages/core/src/Popover/Popover.tsx b/packages/core/src/Popover/Popover.tsx
index 8a592ce92c..5f02abb63d 100644
--- a/packages/core/src/Popover/Popover.tsx
+++ b/packages/core/src/Popover/Popover.tsx
@@ -737,6 +737,8 @@ export function Popover({
};
}, [measureOverflow, popover.contentRef]);
+ // Syncs the overflow measurement with the open surface. It measures, then
+ // observes resize and DOM changes until the surface closes.
useIsomorphicLayoutEffect(() => {
if (!popover.isOpen) {
return;
@@ -788,6 +790,8 @@ export function Popover({
};
}, [measureOverflow, popover.isOpen, scheduleOverflowMeasurement]);
+ // Measures overflow again after the content changes while the surface is
+ // open.
useIsomorphicLayoutEffect(() => {
if (!popover.isOpen) {
return;
diff --git a/packages/core/src/ProgressBar/ProgressBarTouch.ts b/packages/core/src/ProgressBar/ProgressBarTouch.ts
index fd0db7cda3..d990703d99 100644
--- a/packages/core/src/ProgressBar/ProgressBarTouch.ts
+++ b/packages/core/src/ProgressBar/ProgressBarTouch.ts
@@ -75,6 +75,8 @@ export function useProgressBarTouch(
const watchesTrack = isTouch && hasMarks;
const trackRef = useRef<HTMLDivElement | null>(null);
const [trackWidth, setTrackWidth] = useState(0);
+ // Syncs the shared resize observer with the track while the track width is
+ // needed.
useEffect(() => {
const element = trackRef.current;
if (!watchesTrack || element == null) {
diff --git a/packages/core/src/Resizable/ResizeHandle.tsx b/packages/core/src/Resizable/ResizeHandle.tsx
index 1c10a60e99..8da9443be0 100644
--- a/packages/core/src/Resizable/ResizeHandle.tsx
+++ b/packages/core/src/Resizable/ResizeHandle.tsx
@@ -517,6 +517,8 @@ export function ResizeHandle({
// are released here. The region outlives this handle and still has to hear
// that its gesture is over.
const hasRegion = resizable != null;
+ // Interrupts the region's gesture when the handle loses its region or
+ // unmounts.
useEffect(() => {
if (!hasRegion) {
return;
diff --git a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.tsx b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.tsx
index 47b78f6872..f86f41ec24 100644
--- a/packages/core/src/Table/plugins/columnResize/useTableColumnResize.tsx
+++ b/packages/core/src/Table/plugins/columnResize/useTableColumnResize.tsx
@@ -865,7 +865,7 @@ export function useTableColumnResize<T extends Record<string, unknown>>(
}
}, []);
- // Clean up observer on unmount
+ // Releases the table resize observer on unmount.
useEffect(() => {
return () => {
unobserveTableRef.current?.();
@@ -934,6 +934,7 @@ export function useTableColumnResize<T extends Record<string, unknown>>(
};
}, []);
+ // Releases the resize gate on unmount.
useEffect(() => {
return () => {
gateCleanupRef.current?.();
diff --git a/packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx b/packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx
index 0d0f76d2c8..06bccd8dd3 100644
--- a/packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx
+++ b/packages/core/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx
@@ -439,6 +439,8 @@ function PanelDividerModeWatch({
const {mode} = useTheme();
const themeName = useThemeName();
const lastRef = useRef({mode, themeName});
+ // Syncs the panel dividers with the computed theme CSS after a color mode or
+ // theme change.
useLayoutEffect(() => {
const last = lastRef.current;
if (last.mode === mode && last.themeName === themeName) {
@@ -703,6 +705,8 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
}
}
}, []);
+ // Syncs the chevron transitions with the `animatedLayout` handle. Without a
+ // handle, the chevrons use the theme's turn.
useLayoutEffect(() => {
if (animatedLayout == null) {
resetChevrons();
diff --git a/packages/core/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx b/packages/core/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx
index 332d465f4f..cf0428dc2e 100644
--- a/packages/core/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx
+++ b/packages/core/src/Table/plugins/stickyColumns/useTableStickyColumns.tsx
@@ -432,6 +432,8 @@ function PinnedDividerModeWatch({
const {mode} = useTheme();
const themeName = useThemeName();
const lastRef = useRef({mode, themeName});
+ // Syncs the pinned divider with the computed theme CSS after a color mode or
+ // theme change.
useLayoutEffect(() => {
const last = lastRef.current;
if (last.mode !== mode || last.themeName !== themeName) {
diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsx
index 1ba2ead139..32d0d067ba 100644
--- a/packages/core/src/TimeInput/TimeInput.tsx
+++ b/packages/core/src/TimeInput/TimeInput.tsx
@@ -491,6 +491,8 @@ function TimeField({
// region mounted together with its content is not reliably announced.
// Ungrouped mode delegates to Field -> FieldStatus, which announces itself.
const announce = useAnnounce();
+ // Syncs the live region with `status.message` when the field is in an
+ // InputGroup.
useEffect(() => {
if (inputGroup && status?.message) {
announce(
diff --git a/packages/core/src/Timer/Timer.tsx b/packages/core/src/Timer/Timer.tsx
index fe37d0138b..141a7d65f0 100644
--- a/packages/core/src/Timer/Timer.tsx
+++ b/packages/core/src/Timer/Timer.tsx
@@ -186,6 +186,7 @@ export function Timer({
const resolvedFormat = resolveFormat(format);
const initialPresentation = getPresentation(0, resolvedFormat);
+ // Syncs the elapsed-time text with a timer.
useEffect(() => {
const resolvedStartTime =
startTime !== undefined && Number.isFinite(startTime)
diff --git a/packages/core/src/Timestamp/Timestamp.tsx b/packages/core/src/Timestamp/Timestamp.tsx
index ebb2323e0b..ab80ca3ed7 100644
--- a/packages/core/src/Timestamp/Timestamp.tsx
+++ b/packages/core/src/Timestamp/Timestamp.tsx
@@ -378,7 +378,7 @@ export function Timestamp({
? formatInstant(date, 'full', locale, {timeZoneNameStyle: 'long'})
: '';
- // Live updates
+ // Syncs the relative time with an interval timer while the timestamp is live.
useEffect(() => {
if (!isLive || !isValidDate || !isRelativeFormat(effectiveFormat)) {
return;
diff --git a/packages/core/src/Toast/ToastViewport.tsx b/packages/core/src/Toast/ToastViewport.tsx
index dd4caeb4fb..4246baf32b 100644
--- a/packages/core/src/Toast/ToastViewport.tsx
+++ b/packages/core/src/Toast/ToastViewport.tsx
@@ -757,6 +757,8 @@ export function ToastViewport({
};
}, [isTopLayer]);
+ // Syncs the host's place with the modal outlet registry. The host moves into
+ // the latest open modal, and back when that modal closes.
useLayoutEffect(() => {
if (!isTopLayer || host == null) {
return;
diff --git a/packages/core/src/Toast/useToast.tsx b/packages/core/src/Toast/useToast.tsx
index e93d48318e..084fadbcb3 100644
--- a/packages/core/src/Toast/useToast.tsx
+++ b/packages/core/src/Toast/useToast.tsx
@@ -91,6 +91,7 @@ function getFallbackContext(): ToastContextValue {
const FallbackCapture = () => {
const ctx = use(ToastContext);
const doneRef = useRef(false);
+ // Syncs the module-level fallback with the first toast context that mounts.
useEffect(() => {
if (ctx && !doneRef.current) {
doneRef.current = true;
diff --git a/packages/core/src/hooks/ModalAnnounceProvider.tsx b/packages/core/src/hooks/ModalAnnounceProvider.tsx
index dafcdc6c8c..41879c237c 100644
--- a/packages/core/src/hooks/ModalAnnounceProvider.tsx
+++ b/packages/core/src/hooks/ModalAnnounceProvider.tsx
@@ -133,6 +133,7 @@ export function ModalAnnounceProvider({
);
sessionRef.current = {dialog, stop};
}, [dialogRef, isOpen]);
+ // Releases the presentation watch and the held announcements on unmount.
useEffect(
() => () => {
const session = sessionRef.current;
diff --git a/packages/core/src/hooks/useAnnounceRenderedText.ts b/packages/core/src/hooks/useAnnounceRenderedText.ts
index 90a920efc9..37c11ac017 100644
--- a/packages/core/src/hooks/useAnnounceRenderedText.ts
+++ b/packages/core/src/hooks/useAnnounceRenderedText.ts
@@ -135,6 +135,7 @@ export function useAnnounceRenderedText(
);
const isFirstRunRef = useRef(true);
+ // Syncs the live region with the rendered text.
// No dependency array: the text lives in the DOM, and a caller can change it
// without a prop that this hook sees. One text read per render is cheap, and
// the dedupe below makes later renders no-ops.
diff --git a/packages/core/src/hooks/useAutoMediaMode.ts b/packages/core/src/hooks/useAutoMediaMode.ts
index 1db042429b..012e7ac152 100644
--- a/packages/core/src/hooks/useAutoMediaMode.ts
+++ b/packages/core/src/hooks/useAutoMediaMode.ts
@@ -160,6 +160,7 @@ export function useAutoMediaMode(
const {tokens} = useTheme();
const lastRef = useRef<{background: string; tokens: unknown} | null>(null);
+ // Syncs the media mode with the painted color behind the element.
// No dependency array. A surface color is a painted value, and it changes
// when a prop on some ancestor changes. No dependency that this hook can
// name catches that. So the measurement runs on each render, and it skips
diff --git a/packages/core/src/hooks/useBusyAnnouncement.ts b/packages/core/src/hooks/useBusyAnnouncement.ts
index 9b98ac171d..26fa8fe73c 100644
--- a/packages/core/src/hooks/useBusyAnnouncement.ts
+++ b/packages/core/src/hooks/useBusyAnnouncement.ts
@@ -45,6 +45,8 @@ export function useBusyAnnouncement(
// Or how to take back its write inside a modal, wherever the modal moves
// it, until it settles.
const modalMessageRef = useRef<WithdrawAnnouncement | null>(null);
+ // Syncs the live region with `isBusy`. When it becomes true, the busy message
+ // is announced one frame later.
useEffect(() => {
if (!isBusy) {
hasAnnouncedRef.current = false;
diff --git a/packages/core/src/hooks/useDevWarning.ts b/packages/core/src/hooks/useDevWarning.ts
index 94553acb1b..b302e0e24e 100644
--- a/packages/core/src/hooks/useDevWarning.ts
+++ b/packages/core/src/hooks/useDevWarning.ts
@@ -40,6 +40,8 @@ export function useDevWarning(
condition: boolean = true,
): void {
const hasWarnedRef = useRef(false);
+ // The console is outside React. The ref prints the warning one time, also
+ // when StrictMode runs the Effect again.
useEffect(() => {
if (condition && !hasWarnedRef.current) {
hasWarnedRef.current = true;
diff --git a/packages/core/src/hooks/useFocusTrap.ts b/packages/core/src/hooks/useFocusTrap.ts
index 9e9203f116..25402f01e0 100644
--- a/packages/core/src/hooks/useFocusTrap.ts
+++ b/packages/core/src/hooks/useFocusTrap.ts
@@ -50,6 +50,8 @@ export function hasActiveFocusTrapEscape(): boolean {
* second dismissal owner.
*/
export function useFocusTrapEscapeCompatibilitySignal(isActive: boolean): void {
+ // Syncs the module count of active Escape traps with `isActive`. The
+ // compatibility signal reads this count.
useEffect(() => {
if (!isActive) {
return;
diff --git a/packages/core/src/hooks/useHotkeys.ts b/packages/core/src/hooks/useHotkeys.ts
index 4ba1f27e00..5aae94d30c 100644
--- a/packages/core/src/hooks/useHotkeys.ts
+++ b/packages/core/src/hooks/useHotkeys.ts
@@ -157,6 +157,8 @@ export function useHotkeys(hotkeys: Hotkey[]): void {
hotkeysRef.current = hotkeys;
});
+ // Syncs a window keydown listener with this mount. The listener runs the
+ // first hotkey that matches.
useEffect(() => {
const isApple = isApplePlatform();
diff --git a/packages/core/src/hooks/useImageMode.ts b/packages/core/src/hooks/useImageMode.ts
index 3364cc3b9f..e2f2ed6a2b 100644
--- a/packages/core/src/hooks/useImageMode.ts
+++ b/packages/core/src/hooks/useImageMode.ts
@@ -73,6 +73,8 @@ export function useImageMode(
mode: 'dark' | 'light' | null;
} | null>(null);
+ // Syncs the mode with the image at `src`. It fetches and decodes the image,
+ // then samples its pixels.
useEffect(() => {
if (!src) {
return;
diff --git a/packages/core/src/hooks/useKeyboardHint.tsx b/packages/core/src/hooks/useKeyboardHint.tsx
index 2ca68d2c8e..d87338cac1 100644
--- a/packages/core/src/hooks/useKeyboardHint.tsx
+++ b/packages/core/src/hooks/useKeyboardHint.tsx
@@ -244,7 +244,7 @@ export function useKeyboardHint(
[clearDismissTimeout, dismiss, dismissAfterMs, isEnabled, layer],
);
- // Cleanup on unmount
+ // Releases the dismiss timer and the layer anchor on unmount.
useEffect(
() => () => {
clearDismissTimeout();
diff --git a/packages/core/src/hooks/useMenuHover.ts b/packages/core/src/hooks/useMenuHover.ts
index 0bdada81b1..14e7c38fdd 100644
--- a/packages/core/src/hooks/useMenuHover.ts
+++ b/packages/core/src/hooks/useMenuHover.ts
@@ -297,6 +297,7 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
};
}, [clearTimeouts, hideAndRestoreFocus]);
+ // Releases the hover timers on unmount.
useEffect(() => {
return () => clearTimeouts();
}, [clearTimeouts]);
diff --git a/packages/core/src/hooks/useMenuPress.ts b/packages/core/src/hooks/useMenuPress.ts
index 97086b473a..56da934682 100644
--- a/packages/core/src/hooks/useMenuPress.ts
+++ b/packages/core/src/hooks/useMenuPress.ts
@@ -831,6 +831,8 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
endGesture();
}, [endGesture, step]);
+ // Syncs the document listeners of the menu gesture counter with this mount.
+ // Unmount ends the gesture.
useEffect(() => {
// Install the gesture counter's listeners before the first press.
currentGesture();
diff --git a/packages/core/src/hooks/useOverflow.ts b/packages/core/src/hooks/useOverflow.ts
index 8df30b94d3..7991b5b530 100644
--- a/packages/core/src/hooks/useOverflow.ts
+++ b/packages/core/src/hooks/useOverflow.ts
@@ -251,7 +251,8 @@ export function useOverflow(
[calculate],
);
- // Recalculate when itemCount changes
+ // Syncs the visible count with the rendered layout. It measures again after
+ // the items change.
useIsomorphicLayoutEffect(() => {
calculate();
}, [calculate]);
diff --git a/packages/core/src/hooks/usePressFeedback.ts b/packages/core/src/hooks/usePressFeedback.ts
index d3292cf6be..d8801ab514 100644
--- a/packages/core/src/hooks/usePressFeedback.ts
+++ b/packages/core/src/hooks/usePressFeedback.ts
@@ -50,6 +50,7 @@ import {installPressFeedback, pressableProps} from '../utils/pressFeedback';
* ```
*/
export function usePressFeedback(): typeof pressableProps {
+ // Syncs the shared document listener for press feedback with this mount.
useEffect(() => installPressFeedback(), []);
return pressableProps;
}
diff --git a/packages/core/src/hooks/useScrollLock.ts b/packages/core/src/hooks/useScrollLock.ts
index d5bdb30c73..45f37ec9c5 100644
--- a/packages/core/src/hooks/useScrollLock.ts
+++ b/packages/core/src/hooks/useScrollLock.ts
@@ -54,6 +54,8 @@ let activeLock: ActiveLock | null = null;
* ```
*/
export function useScrollLock(isLocked: boolean): void {
+ // Syncs the document's scroll lock with `isLocked`. A count of holders keeps
+ // the page locked until the last one releases.
useEffect(() => {
if (!isLocked) {
return;
diff --git a/packages/core/src/hooks/useScrollableArea.ts b/packages/core/src/hooks/useScrollableArea.ts
index afdbf1b66e..56635041b0 100644
--- a/packages/core/src/hooks/useScrollableArea.ts
+++ b/packages/core/src/hooks/useScrollableArea.ts
@@ -216,6 +216,8 @@ export function useScrollableArea({
const getComposedViewportRef = useStableComposedRef(viewportRef);
const getComposedContentRef = useStableComposedRef(contentRef);
+ // Syncs the scroll geometry with the viewport and content nodes. It measures
+ // them, then follows resize, scroll, transition and font events.
useIsomorphicLayoutEffect(() => {
if (viewport == null || content == null) {
return;
@@ -430,6 +432,8 @@ export function useScrollableArea({
// commit. A loss waits for the next frame.
const previousOverflowRef = useRef<LogicalOverflowGeometry>(INITIAL_OVERFLOW);
const previousMappingRef = useRef<LogicalAxisMapping>(INITIAL_MAPPING);
+ // Measures the layout again when overflow starts or the writing-mode mapping
+ // changes. A new scrollbar gutter changes the geometry.
useIsomorphicLayoutEffect(() => {
const previous = previousOverflowRef.current;
const hasGainedOverflow =
diff --git a/packages/core/src/hooks/useStreamingText.ts b/packages/core/src/hooks/useStreamingText.ts
index 271073482d..432f6bf59d 100644
--- a/packages/core/src/hooks/useStreamingText.ts
+++ b/packages/core/src/hooks/useStreamingText.ts
@@ -178,6 +178,8 @@ export function useStreamingText(
'(prefers-reduced-motion: reduce)',
);
+ // Syncs the revealed text with an animation-frame clock while the text
+ // streams.
useEffect(() => {
if (!isStreaming || speed === 'instant' || prefersReducedMotion) {
return;
diff --git a/packages/core/src/theme/Theme.tsx b/packages/core/src/theme/Theme.tsx
index f31718ae8d..e99bada9ba 100644
--- a/packages/core/src/theme/Theme.tsx
+++ b/packages/core/src/theme/Theme.tsx
@@ -120,6 +120,7 @@ const THEME_LAYER_ORDER = '@layer reset, astryx-base, astryx-theme;';
function useThemeStyleInjection(theme: DefinedTheme): void {
const id = useId();
+ // Syncs the document's stylesheets with the runtime theme CSS.
useInsertionEffect(() => {
// Built themes have their CSS in a separate file — skip injection
if (theme.__built) {
@@ -218,6 +219,7 @@ function useRootThemeSync(
themeName: string,
reducesMotion: boolean,
): void {
+ // Syncs the theme attributes on the root `<html>` element.
useIsomorphicLayoutEffect(() => {
if (isNested) {
return;
diff --git a/packages/core/src/utils/interactionModality.ts b/packages/core/src/utils/interactionModality.ts
index 6f4afed7d7..ef555a24d3 100644
--- a/packages/core/src/utils/interactionModality.ts
+++ b/packages/core/src/utils/interactionModality.ts
@@ -203,6 +203,7 @@ function holdNodeDocument(
* tracker of its own for modality.
*/
export function useInteractionModalityTracking(): InteractionModalityTracking {
+ // Syncs the document's interaction-modality tracking with this mount.
useEffect(() => trackInteractionModality(), []);
const nodeRef = useRef<Element | null>(null);
const holdRef = useRef<{release: (() => void) | null}>({release: null});
@@ -236,7 +237,10 @@ export function useInteractionModalityTracking(): InteractionModalityTracking {
export function useInteractionModalityTrackingFor(
elementRef: RefObject<Element | null>,
): () => InteractionModality {
+ // Syncs the document's interaction-modality tracking with this mount.
useEffect(() => trackInteractionModality(), []);
+ // Syncs modality tracking in the element's second document, such as an iframe
+ // or a Picture-in-Picture window.
useEffect(() => {
const ownerDocument = elementRef.current?.ownerDocument;
if (