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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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 reopendiff --git a/packages/core/src/Chat/ChatMessageList.tsx b/packages/core/src/Chat/ChatMessageList.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 ownerdiff --git a/packages/core/src/DateInput/MonthScroller.tsx b/packages/core/src/DateInput/MonthScroller.tsxindex 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 zerodiff --git a/packages/core/src/DateInput/TouchDateField.tsx b/packages/core/src/DateInput/TouchDateField.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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 skipsdiff --git a/packages/core/src/hooks/useBusyAnnouncement.ts b/packages/core/src/hooks/useBusyAnnouncement.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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 injectionif (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.tsindex 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 (