fix(core): Change useMutationObserver to useMutationObserverRef

.changeset/tangy-items-give.md

@@ -0,0 +1,5 @@
+---
+'@vapor-ui/core': patch
+---
+
+Change useMutationObserver hook to use only ref

packages/core/src/components/navigation-menu/navigation-menu.tsx

@@ -7,7 +7,7 @@ import { NavigationMenu as BaseNavigationMenu } from '@base-ui-components/react'
 import { ChevronDownOutlineIcon } from '@vapor-ui/icons';
 import clsx from 'clsx';
 
-import { useMutationObserver } from '~/hooks/use-mutation-observer';
+import { useMutationObserverRef } from '~/hooks/use-mutation-observer-ref';
 import { createContext } from '~/libs/create-context';
 import { createSlot } from '~/libs/create-slot';
 import { vars } from '~/styles/themes.css';
@@ -296,7 +296,7 @@ export const NavigationMenuPopupPrimitive = forwardRef<
         if (initialAlign) setAlign(initialAlign);
     }, []);
 
-    const arrowRef = useMutationObserver<HTMLDivElement>({
+    const arrowRef = useMutationObserverRef<HTMLDivElement>({
         callback: (mutations) => {
             mutations.forEach((mutation) => {
                 const { attributeName, target: mutationTarget } = mutation;

packages/core/src/components/popover/popover.tsx

@@ -6,7 +6,7 @@ import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
 import { Popover as BasePopover } from '@base-ui-components/react/popover';
 import clsx from 'clsx';
 
-import { useMutationObserver } from '~/hooks/use-mutation-observer';
+import { useMutationObserverRef } from '~/hooks/use-mutation-observer-ref';
 import { createSlot } from '~/libs/create-slot';
 import { vars } from '~/styles/themes.css';
 import { composeRefs } from '~/utils/compose-refs';
@@ -113,7 +113,7 @@ export const PopoverPopupPrimitive = forwardRef<HTMLDivElement, PopoverPopupPrim
             if (initialAlign) setAlign(initialAlign);
         }, []);
 
-        const arrowRef = useMutationObserver<HTMLDivElement>({
+        const arrowRef = useMutationObserverRef<HTMLDivElement>({
             callback: (mutations) => {
                 mutations.forEach((mutation) => {
                     const { attributeName, target: mutationTarget } = mutation;

packages/core/src/components/tooltip/tooltip.tsx

@@ -6,7 +6,7 @@ import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
 import { Tooltip as BaseTooltip } from '@base-ui-components/react/tooltip';
 import clsx from 'clsx';
 
-import { useMutationObserver } from '~/hooks/use-mutation-observer';
+import { useMutationObserverRef } from '~/hooks/use-mutation-observer-ref';
 import { createSlot } from '~/libs/create-slot';
 import { vars } from '~/styles/themes.css';
 import { composeRefs } from '~/utils/compose-refs';
@@ -111,7 +111,7 @@ export const TooltipPopupPrimitive = forwardRef<HTMLDivElement, TooltipPopupPrim
             if (initialAlign) setAlign(initialAlign);
         }, []);
 
-        const arrowRef = useMutationObserver<HTMLDivElement>({
+        const arrowRef = useMutationObserverRef<HTMLDivElement>({
             callback: (mutations) => {
                 mutations.forEach((mutation) => {
                     const { attributeName, target: mutationTarget } = mutation;

packages/core/src/hooks/use-mutation-observer-ref.test.tsx

@@ -0,0 +1,201 @@
+import { render, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { useMutationObserverRef } from './use-mutation-observer-ref';
+
+describe('useMutationObserverRef', () => {
+    it('should observe mutations on the attached element', async () => {
+        const callback = vi.fn();
+        let testRef = null as HTMLDivElement | null;
+
+        function TestComponent() {
+            const ref = useMutationObserverRef<HTMLDivElement>({
+                callback,
+                options: { attributes: true, attributeFilter: ['data-test'] },
+            });
+
+            return (
+                <div
+                    ref={(node) => {
+                        testRef = node;
+                        ref(node);
+                    }}
+                    data-test="initial"
+                >
+                    Test Content
+                </div>
+            );
+        }
+
+        render(<TestComponent />);
+
+        // Wait for the component to mount and observer to be set up
+        await waitFor(() => expect(testRef).not.toBeNull());
+
+        // Trigger a mutation
+        testRef!.setAttribute('data-test', 'changed');
+
+        // Wait for the callback to be called
+        await waitFor(() => {
+            expect(callback).toHaveBeenCalled();
+        });
+
+        expect(callback.mock.calls[0][0]).toHaveLength(1);
+        expect(callback.mock.calls[0][0][0].type).toBe('attributes');
+        expect(callback.mock.calls[0][0][0].attributeName).toBe('data-test');
+    });
+
+    it('should disconnect observer when ref is set to null', async () => {
+        const callback = vi.fn();
+
+        function TestComponent({ show }: { show: boolean }) {
+            const ref = useMutationObserverRef<HTMLDivElement>({
+                callback,
+                options: { attributes: true },
+            });
+
+            if (!show) return null;
+
+            return (
+                <div ref={ref} data-test="value">
+                    Test Content
+                </div>
+            );
+        }
+
+        const { rerender } = render(<TestComponent show={true} />);
+
+        // Unmount the component
+        rerender(<TestComponent show={false} />);
+
+        // The observer should be disconnected, so no further mutations should be observed
+        await waitFor(() => {
+            expect(callback).not.toHaveBeenCalled();
+        });
+    });
+
+    it('should update to the latest callback on each render', async () => {
+        const firstCallback = vi.fn();
+        const secondCallback = vi.fn();
+        let testRef = null as HTMLDivElement | null;
+
+        function TestComponent({ callback }: { callback: (mutations: MutationRecord[]) => void }) {
+            const ref = useMutationObserverRef<HTMLDivElement>({
+                callback,
+                options: { attributes: true, attributeFilter: ['data-test'] },
+            });
+
+            return (
+                <div
+                    ref={(node) => {
+                        testRef = node;
+                        ref(node);
+                    }}
+                    data-test="initial"
+                >
+                    Test Content
+                </div>
+            );
+        }
+
+        const { rerender } = render(<TestComponent callback={firstCallback} />);
+
+        await waitFor(() => expect(testRef).not.toBeNull());
+
+        // Trigger first mutation
+        testRef!.setAttribute('data-test', 'changed1');
+
+        await waitFor(() => {
+            expect(firstCallback).toHaveBeenCalled();
+        });
+
+        // Clear the first callback and switch to second
+        firstCallback.mockClear();
+        rerender(<TestComponent callback={secondCallback} />);
+
+        // Trigger second mutation
+        testRef!.setAttribute('data-test', 'changed2');
+
+        await waitFor(() => {
+            expect(secondCallback).toHaveBeenCalled();
+        });
+
+        // First callback should not have been called again
+        expect(firstCallback).not.toHaveBeenCalled();
+    });
+
+    it('should observe child list mutations when configured', async () => {
+        const callback = vi.fn();
+        let testRef = null as HTMLDivElement | null;
+
+        function TestComponent() {
+            const ref = useMutationObserverRef<HTMLDivElement>({
+                callback,
+                options: { childList: true },
+            });
+
+            return (
+                <div
+                    ref={(node) => {
+                        testRef = node;
+                        ref(node);
+                    }}
+                >
+                    <span>Initial Child</span>
+                </div>
+            );
+        }
+
+        render(<TestComponent />);
+
+        await waitFor(() => expect(testRef).not.toBeNull());
+
+        // Add a new child
+        const newChild = document.createElement('span');
+        newChild.textContent = 'New Child';
+        testRef!.appendChild(newChild);
+
+        await waitFor(() => {
+            expect(callback).toHaveBeenCalled();
+        });
+
+        expect(callback.mock.calls[0][0][0].type).toBe('childList');
+    });
+
+    it('should return cleanup function that disconnects observer (React 19+ support)', async () => {
+        const callback = vi.fn();
+        let cleanupFn: (() => void) | undefined;
+
+        function TestComponent() {
+            const ref = useMutationObserverRef<HTMLDivElement>({
+                callback,
+                options: { attributes: true },
+            });
+
+            return (
+                <div
+                    ref={(node) => {
+                        const cleanup = ref(node);
+                        // Store cleanup function if returned (React 19+)
+                        if (typeof cleanup === 'function') {
+                            cleanupFn = cleanup;
+                        }
+                    }}
+                    data-test="initial"
+                >
+                    Test Content
+                </div>
+            );
+        }
+
+        const { unmount } = render(<TestComponent />);
+
+        // If cleanup function was returned, it should work
+        if (cleanupFn) {
+            cleanupFn();
+            expect(callback).not.toHaveBeenCalled();
+        }
+
+        unmount();
+    });
+});

packages/core/src/hooks/use-mutation-observer-ref.ts

@@ -0,0 +1,67 @@
+import { useCallback, useRef } from 'react';
+
+interface Params {
+    callback: (mutations: MutationRecord[]) => void;
+    options?: MutationObserverInit;
+}
+
+/**
+ * A hook that returns a callback ref which sets up a MutationObserver
+ * when attached to a DOM element.
+ *
+ * This implementation uses callback refs instead of useEffect to avoid
+ * issues with stale dependencies and unnecessary observer recreation.
+ * It stores the callback and options in refs to maintain stable references
+ * across renders, ensuring compatibility with React 17+.
+ *
+ * For React 19+, the callback ref returns a cleanup function that will
+ * automatically disconnect the observer when the ref changes or unmounts.
+ *
+ * @see https://tkdodo.eu/blog/ref-callbacks-react-19-and-the-compiler
+ *
+ * @example
+ * const ref = useMutationObserverRef({
+ *   callback: (mutations) => console.log(mutations),
+ *   options: { attributes: true }
+ * });
+ *
+ * return <div ref={ref}>Content</div>;
+ */
+export const useMutationObserverRef = <T extends HTMLElement>({ callback, options }: Params) => {
+    const observerRef = useRef<MutationObserver | null>(null);
+    const callbackRef = useRef(callback);
+    const optionsRef = useRef(options);
+
+    // Keep refs up to date with latest values
+    callbackRef.current = callback;
+    optionsRef.current = options;
+
+    const refCallback = useCallback((node: T | null) => {
+        // Cleanup previous observer if it exists
+        if (observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+        }
+
+        // Set up new observer if node is present
+        if (node) {
+            // Use the refs to get the latest callback and options
+            const observer = new MutationObserver((mutations) => {
+                callbackRef.current(mutations);
+            });
+            observer.observe(node, optionsRef.current);
+            observerRef.current = observer;
+
+            // Return cleanup function for React 19+
+            // For React 17-18, this return value is ignored
+            return () => {
+                observer.disconnect();
+                if (observerRef.current === observer) {
+                    observerRef.current = null;
+                }
+            };
+        }
+    }, []); // Empty dependency array - stable across all renders
+
+    return refCallback;
+};