react-magic-portal 1.1.9 → 1.2.1

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [1.2.1](https://github.com/molvqingtai/react-magic-portal/compare/v1.2.0...v1.2.1) (2025-10-10)
+
+
+### Bug Fixes
+
+* fix issue of text nodes not being updated & suppress React runtime warnings ([7307c2a](https://github.com/molvqingtai/react-magic-portal/commit/7307c2ad08be8a27a3e55522b0b9f14e501c61d2))
+
+# [1.2.0](https://github.com/molvqingtai/react-magic-portal/compare/v1.1.9...v1.2.0) (2025-10-10)
+
+
+### Features
+
+* add root prop to customize MutationObserver scope ([e27aeeb](https://github.com/molvqingtai/react-magic-portal/commit/e27aeeb70ae2b93f9f6ac80d25deb436ca125065))
+
+
+### Performance Improvements
+
+* optimize node insertion with position check ([866947b](https://github.com/molvqingtai/react-magic-portal/commit/866947bba294d2887c30a9ce4670ecf6b5429b05))
+
 ## [1.1.9](https://github.com/molvqingtai/react-magic-portal/compare/v1.1.8...v1.1.9) (2025-10-09)
 
 

package/README.md

@@ -97,13 +97,14 @@ function App() {
 
 ### Props
 
-| Prop        | Type                                                                                       | Default      | Description                                                  |
-| ----------- | ------------------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------ |
-| `anchor`    | `string \| (() => Element \| null) \| Element \| React.RefObject<Element \| null> \| null` | **Required** | The target element where the portal content will be rendered |
-| `position`  | `'append' \| 'prepend' \| 'before' \| 'after'`                                             | `'append'`   | Position relative to the anchor element                      |
-| `children`  | `React.ReactElement \| React.ReactElement[]`                                               | `undefined`  | The content to render in the portal                          |
-| `onMount`   | `(anchor: Element, container: Element) => void`                                            | `undefined`  | Callback fired when the portal is mounted                    |
-| `onUnmount` | `(anchor: Element, container: Element) => void`                                            | `undefined`  | Callback fired when the portal is unmounted                  |
+| Prop        | Type                                                                                       | Default         | Description                                                  |
+| ----------- | ------------------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------ |
+| `anchor`    | `string \| (() => Element \| null) \| Element \| React.RefObject<Element \| null> \| null` | **Required**    | The target element where the portal content will be rendered |
+| `position`  | `'append' \| 'prepend' \| 'before' \| 'after'`                                             | `'append'`      | Position relative to the anchor element                      |
+| `root`      | `Element`                                                                                  | `document.body` | The root element to observe for DOM mutations                |
+| `children`  | `React.ReactElement \| React.ReactElement[]`                                               | `undefined`     | The content to render in the portal                          |
+| `onMount`   | `(anchor: Element, container: Element) => void`                                            | `undefined`     | Callback fired when the portal is mounted                    |
+| `onUnmount` | `(anchor: Element, container: Element) => void`                                            | `undefined`     | Callback fired when the portal is unmounted                  |
 
 ### Anchor Types
 

package/__tests__/eslint.config.ts

@@ -3,8 +3,7 @@ import pluginJs from '@eslint/js'
 import { defineConfig } from 'eslint/config'
 import tseslint from 'typescript-eslint'
 import prettierPlugin from 'eslint-plugin-prettier/recommended'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
+import eslintReact from '@eslint-react/eslint-plugin'
 
 export default defineConfig([
   {
@@ -18,13 +17,13 @@ export default defineConfig([
     }
   },
   pluginJs.configs.recommended,
-  ...tseslint.configs.recommended,
+  tseslint.configs.recommended,
+  eslintReact.configs['recommended-typescript'],
   prettierPlugin,
-  reactHooks.configs['recommended-latest'],
-  reactRefresh.configs.vite,
   {
     rules: {
-      '@typescript-eslint/no-explicit-any': 'off'
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@eslint-react/no-forward-ref': 'off'
     }
   }
 ])

package/__tests__/package.json

@@ -18,25 +18,24 @@
     "react-magic-portal": "workspace:*"
   },
   "devDependencies": {
-    "@eslint/js": "^9.36.0",
+    "@eslint-react/eslint-plugin": "^2.0.6",
+    "@eslint/js": "^9.37.0",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "@types/react": "^19.1.15",
-    "@types/react-dom": "^19.1.9",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
     "@vitejs/plugin-react": "^5.0.4",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
-    "eslint": "^9.36.0",
+    "eslint": "^9.37.0",
     "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-react-hooks": "^5.2.0",
-    "eslint-plugin-react-refresh": "^0.4.22",
     "globals": "^16.4.0",
-    "happy-dom": "^19.0.2",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.45.0",
-    "vite": "^7.1.7",
+    "happy-dom": "^20.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.0",
+    "vite": "^7.1.9",
     "vitest": "^3.2.4"
   }
 }

package/__tests__/src/magic-portal.test.tsx

@@ -47,7 +47,9 @@ describe('MagicPortal', () => {
 
         return (
           <div>
-            <button onClick={() => setShowAnchor(true)}>Show Anchor</button>
+            <button type="button" onClick={() => setShowAnchor(true)}>
+              Show Anchor
+            </button>
             {showAnchor && <div id="dynamic-anchor">Anchor</div>}
             <MagicPortal anchor="#dynamic-anchor">
               <div data-testid="portal-content">Portal Content</div>
@@ -74,7 +76,9 @@ describe('MagicPortal', () => {
 
         return (
           <div>
-            <button onClick={() => setShowAnchor(false)}>Hide Anchor</button>
+            <button type="button" onClick={() => setShowAnchor(false)}>
+              Hide Anchor
+            </button>
             {showAnchor && <div id="dynamic-anchor">Anchor</div>}
             <MagicPortal anchor="#dynamic-anchor">
               <div data-testid="portal-content">Portal Content</div>
@@ -435,22 +439,31 @@ describe('MagicPortal', () => {
 
     it('should work with forwardRef components as portal content', () => {
       const ForwardedComponent = React.forwardRef<HTMLButtonElement, { children: React.ReactNode }>(
-        ({ children }, ref) => <button ref={ref}>{children}</button>
+        ({ children }, forwardedRef) => (
+          <button type="button" ref={forwardedRef}>
+            {children}
+          </button>
+        )
       )
 
-      const buttonRef = vi.fn()
+      ForwardedComponent.displayName = 'ForwardedComponent'
+
+      const refCalls: Array<HTMLButtonElement | null> = []
+      const handleButtonRef: React.RefCallback<HTMLButtonElement> = (element) => {
+        refCalls.push(element)
+      }
       const anchor = document.createElement('div')
       anchor.id = 'forward-ref-anchor'
       document.body.appendChild(anchor)
 
       render(
         <MagicPortal anchor="#forward-ref-anchor">
-          <ForwardedComponent ref={buttonRef}>Click me</ForwardedComponent>
+          <ForwardedComponent ref={handleButtonRef}>Click me</ForwardedComponent>
         </MagicPortal>
       )
 
-      expect(buttonRef).toHaveBeenCalledWith(expect.any(HTMLButtonElement))
-      expect(buttonRef.mock.calls[0][0]?.textContent).toBe('Click me')
+      expect(refCalls[0]).toBeInstanceOf(HTMLButtonElement)
+      expect(refCalls[0]?.textContent).toBe('Click me')
     })
 
     it('should handle single element content', () => {
@@ -527,7 +540,9 @@ describe('MagicPortal', () => {
 
         return (
           <div>
-            <button onClick={() => setShowFirst(!showFirst)}>Toggle Content</button>
+            <button type="button" onClick={() => setShowFirst(!showFirst)}>
+              Toggle Content
+            </button>
             <MagicPortal anchor="#dynamic-content-anchor">
               {showFirst ? (
                 <div ref={ref1} data-testid="first-content">
@@ -601,7 +616,9 @@ describe('MagicPortal', () => {
 
         return (
           <div>
-            <button onClick={addElement}>Add Target Element</button>
+            <button type="button" onClick={addElement}>
+              Add Target Element
+            </button>
             <MagicPortal anchor=".dynamic-target">
               <div data-testid="portal-content">Portal Content</div>
             </MagicPortal>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-magic-portal",
-  "version": "1.1.9",
+  "version": "1.2.1",
   "description": "React Portal with dynamic mounting support",
   "main": "packages/component/dist/index.js",
   "type": "module",
@@ -40,7 +40,7 @@
   },
   "homepage": "https://github.com/molvqingtai/react-magic-portal#readme",
   "dependencies": {
-    "@commitlint/cli": "^20.0.0",
+    "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",

package/packages/component/dist/index.d.ts

@@ -4,6 +4,7 @@ import React from "react";
 interface MagicPortalProps {
   anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null;
   position?: 'append' | 'prepend' | 'before' | 'after';
+  root?: Element;
   children?: React.ReactElement | React.ReactElement[];
   onMount?: (anchor: Element, container: Element) => void;
   onUnmount?: (anchor: Element, container: Element) => void;
@@ -12,6 +13,7 @@ declare const MagicPortal: {
   ({
     anchor,
     position,
+    root,
     children,
     onMount,
     onUnmount

package/packages/component/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;UAGiB,gBAAA;0BACS,kBAAkB,UAAU,KAAA,CAAM,UAAU;EADrD,QAAA,CAAA,EAAA,QAAgB,GAAA,SAAA,GAAA,QAAA,GAAA,OAAA;EAAA,QAAA,CAAA,EAGpB,KAAA,CAAM,YAHc,GAGC,KAAA,CAAM,YAHP,EAAA;SACP,CAAA,EAAA,CAAA,MAAA,EAGL,OAHK,EAAA,SAAA,EAGe,OAHf,EAAA,GAAA,IAAA;WAAkB,CAAA,EAAA,CAAA,MAAA,EAIrB,OAJqB,EAAA,SAAA,EAID,OAJC,EAAA,GAAA,IAAA;;cA2DtC,WA3DsD,EAAA;;IAE/C,MAAM;IAAA,QAAA;IAAA,QAAA;IAAA,OAAA;IAAA;EAAA,CAAA,EAyDiE,gBAzDjE,CAAA,EAyDiF,KAAA,CAAA,WAzDjF,GAAA,IAAA;aAAqB,EAAA,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;UAGiB,gBAAA;0BACS,kBAAkB,UAAU,KAAA,CAAM,UAAU;EADrD,QAAA,CAAA,EAAA,QAAgB,GAAA,SAAA,GAAA,QAAA,GAAA,OAAA;EAAA,IAAA,CAAA,EAGxB,OAHwB;UACP,CAAA,EAGb,KAAA,CAAM,YAHO,GAGQ,KAAA,CAAM,YAHd,EAAA;SAAkB,CAAA,EAAA,CAAA,MAAA,EAIvB,OAJuB,EAAA,SAAA,EAIH,OAJG,EAAA,GAAA,IAAA;WAA0B,CAAA,EAAA,CAAA,MAAA,EAK/C,OAL+C,EAAA,SAAA,EAK3B,OAL2B,EAAA,GAAA,IAAA;;cAoEhE,WAlEG,EAAA;;IACI,MAAM;IAAA,QAAA;IAAA,IAAA;IAAA,QAAA;IAAA,OAAA;IAAA;EAAA,CAAA,EAwEhB,gBAxEgB,CAAA,EAwEA,KAAA,CAAA,WAxEA,GAAA,IAAA;aAAqB,EAAA,MAAA"}

package/packages/component/dist/index.js

@@ -1,2 +1,2 @@
-import e,{useCallback as t,useEffect as n,useLayoutEffect as r,useRef as i,useState as a}from"react";import{createPortal as o}from"react-dom";const s=e=>{let t=Object.getOwnPropertyDescriptor(e.props,`ref`)?.get,n=t&&`isReactWarning`in t&&t.isReactWarning;return n?e.ref:(t=Object.getOwnPropertyDescriptor(e,`ref`)?.get,n=t&&`isReactWarning`in t&&t.isReactWarning,n?e.props.ref:e.props.ref||e.ref)},c=e=>typeof e==`string`?document.querySelector(e):typeof e==`function`?e():e&&`current`in e?e.current:e,l=(e,t)=>{if(typeof e==`function`)return e(t);e!=null&&(e.current=t)},u=(...e)=>t=>{let n=e.map(e=>l(e,t));return()=>n.forEach((t,n)=>typeof t==`function`?t():l(e[n],null))},d=({anchor:l,position:d=`append`,children:f,onMount:p,onUnmount:m})=>{let h=i(null),[g,_]=a(null),v=e.Children.map(f,t=>{if(!e.isValidElement(t))return null;let n=s(t);return e.cloneElement(t,{ref:u(n,e=>{e&&h.current?.insertAdjacentElement({before:`beforebegin`,prepend:`afterbegin`,append:`beforeend`,after:`afterend`}[d],e)})})}),y=t(()=>{h.current=c(l),_(d===`prepend`||d===`append`?h.current:h.current?.parentElement??null)},[l,d]);return r(()=>{y();let e=new MutationObserver(e=>{!e.flatMap(({addedNodes:e,removedNodes:t})=>[...e,...t]).some(e=>g?.contains(e))&&y()});return e.observe(document.body,{childList:!0,subtree:!0}),()=>e.disconnect()},[y,l,g]),n(()=>{if(g&&h.current)return p?.(h.current,g),()=>{m?.(h.current,g)}},[p,m,g]),g&&o(v,g)};d.displayName=`MagicPortal`;var f=d;export{f as default};
+import e,{useCallback as t,useEffect as n,useLayoutEffect as r,useRef as i,useState as a}from"react";import{createPortal as o}from"react-dom";const s=e=>{let t=Object.getOwnPropertyDescriptor(e.props,`ref`)?.get,n=t&&`isReactWarning`in t&&t.isReactWarning;return n?e.ref:(t=Object.getOwnPropertyDescriptor(e,`ref`)?.get,n=t&&`isReactWarning`in t&&t.isReactWarning,n?e.props.ref:e.props.ref||e.ref)},c=e=>typeof e==`string`?document.querySelector(e):typeof e==`function`?e():e&&`current`in e?e.current:e,l=(e,t)=>e?t===`prepend`||t===`append`?e:e.parentElement:null,u=(e,t)=>{if(typeof e==`function`)return e(t);e!=null&&(e.current=t)},d=(...e)=>t=>{let n=e.map(e=>u(e,t));return()=>n.forEach((t,n)=>typeof t==`function`?t():u(e[n],null))},f=({anchor:u,position:f=`append`,root:p=document.body,children:m,onMount:h,onUnmount:g})=>{let _=i(null),[v,y]=a(null),b=t(e=>{if(!e)return;let t=_.current;if(!t)return;let n=l(t,f);if(!n)return;let r=!1;switch(f){case`append`:r=e.parentElement===n&&n.lastChild===e;break;case`prepend`:r=e.parentElement===n&&n.firstChild===e;break;case`before`:r=e.parentElement===n&&t.previousSibling===e;break;case`after`:r=e.parentElement===n&&t.nextSibling===e;break}r||t.insertAdjacentElement({before:`beforebegin`,prepend:`afterbegin`,append:`beforeend`,after:`afterend`}[f],e)},[f]),x=e.Children.map(m,t=>{if(!e.isValidElement(t))return null;let n=s(t);return e.cloneElement(t,{ref:d(n,b)})}),S=t(()=>{_.current=c(u);let e=l(_.current,f);e&&(e.__reactWarnedAboutChildrenConflict=!0),y(e)},[u,f]);return r(()=>{S();let e=new MutationObserver(e=>{!e.flatMap(({addedNodes:e,removedNodes:t})=>[...e,...t]).some(e=>v?.contains(e))&&S()});return e.observe(p,{childList:!0,subtree:!0}),()=>e.disconnect()},[S,u,v,p]),n(()=>{if(v&&_.current)return h?.(_.current,v),()=>{g?.(_.current,v)}},[h,g,v]),v?o(x,v):null};f.displayName=`MagicPortal`;var p=f;export{p as default};
 //# sourceMappingURL=index.js.map

package/packages/component/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import React, { useEffect, useState, useRef, useCallback, useLayoutEffect } from 'react'\nimport { createPortal } from 'react-dom'\n\nexport interface MagicPortalProps {\n  anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null\n  position?: 'append' | 'prepend' | 'before' | 'after'\n  children?: React.ReactElement | React.ReactElement[]\n  onMount?: (anchor: Element, container: Element) => void\n  onUnmount?: (anchor: Element, container: Element) => void\n}\n\n/**\n * https://github.com/radix-ui/primitives/blob/36d954d3c1b41c96b1d2e875b93fc9362c8c09e6/packages/react/slot/src/slot.tsx#L166\n */\nconst getElementRef = (element: React.ReactElement) => {\n  // React <=18 in DEV\n  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get\n  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n  if (mayWarn) {\n    return (element as any).ref as React.Ref<Element>\n  }\n  // React 19 in DEV\n  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get\n  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n  if (mayWarn) {\n    return (element.props as { ref?: React.Ref<Element> }).ref\n  }\n\n  // Not DEV\n  return (element.props as { ref?: React.Ref<Element> }).ref || ((element as any).ref as React.Ref<Element>)\n}\n\nconst resolveAnchor = (anchor: MagicPortalProps['anchor']) => {\n  if (typeof anchor === 'string') {\n    return document.querySelector(anchor)\n  } else if (typeof anchor === 'function') {\n    return anchor()\n  } else if (anchor && 'current' in anchor) {\n    return anchor.current\n  } else {\n    return anchor\n  }\n}\n\n/**\n * https://github.com/facebook/react/blob/d91d28c8ba6fe7c96e651f82fc47c9d5481bf5f9/packages/react-reconciler/src/ReactFiberHooks.js#L2792\n */\nconst setRef = <T>(ref: React.Ref<T> | undefined, value: T) => {\n  if (typeof ref === 'function') {\n    return ref(value)\n  } else if (ref !== null && ref !== undefined) {\n    ref.current = value\n  }\n}\n\nconst mergeRef = <T extends Element | null>(...refs: (React.Ref<T> | undefined)[]) => {\n  return (node: T) => {\n    const cleanups = refs.map((ref) => setRef(ref, node))\n    return () =>\n      cleanups.forEach((cleanup, index) => (typeof cleanup === 'function' ? cleanup() : setRef(refs[index], null)))\n  }\n}\n\nconst MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount }: MagicPortalProps) => {\n  const anchorRef = useRef<Element | null>(null)\n  const [container, setContainer] = useState<Element | null>(null)\n\n  const nodes = React.Children.map(children, (item) => {\n    if (!React.isValidElement(item)) {\n      return null\n    }\n    const originalRef = getElementRef(item)\n    return React.cloneElement(item as React.ReactElement<any>, {\n      ref: mergeRef(originalRef, (node) => {\n        const positionMap = {\n          before: 'beforebegin',\n          prepend: 'afterbegin',\n          append: 'beforeend',\n          after: 'afterend'\n        } as const\n        node && anchorRef.current?.insertAdjacentElement(positionMap[position], node)\n      })\n    })\n  })\n\n  const update = useCallback(() => {\n    anchorRef.current = resolveAnchor(anchor)\n    setContainer(\n      position === 'prepend' || position === 'append' ? anchorRef.current : (anchorRef.current?.parentElement ?? null)\n    )\n  }, [anchor, position])\n\n  useLayoutEffect(() => {\n    update()\n\n    const observer = new MutationObserver((mutations) => {\n      const isSelfMutation = mutations\n        .flatMap(({ addedNodes, removedNodes }) => [...addedNodes, ...removedNodes])\n        .some((node) => container?.contains(node))\n      !isSelfMutation && update()\n    })\n\n    observer.observe(document.body, {\n      childList: true,\n      subtree: true\n    })\n    return () => observer.disconnect()\n  }, [update, anchor, container])\n\n  useEffect(() => {\n    if (container && anchorRef.current) {\n      onMount?.(anchorRef.current, container)\n      return () => {\n        onUnmount?.(anchorRef.current!, container)\n      }\n    }\n  }, [onMount, onUnmount, container])\n\n  return container && createPortal(nodes, container)\n}\n\nMagicPortal.displayName = 'MagicPortal'\n\nexport default MagicPortal\n"],"mappings":"8IAcA,MAAM,EAAiB,GAAgC,CAErD,IAAI,EAAS,OAAO,yBAAyB,EAAQ,MAAO,MAAM,EAAE,IAChE,EAAU,GAAU,mBAAoB,GAAU,EAAO,eAY7D,OAXI,EACM,EAAgB,KAG1B,EAAS,OAAO,yBAAyB,EAAS,MAAM,EAAE,IAC1D,EAAU,GAAU,mBAAoB,GAAU,EAAO,eACrD,EACM,EAAQ,MAAuC,IAIjD,EAAQ,MAAuC,KAAS,EAAgB,MAG5E,EAAiB,GACjB,OAAO,GAAW,SACb,SAAS,cAAc,EAAO,CAC5B,OAAO,GAAW,WACpB,GAAQ,CACN,GAAU,YAAa,EACzB,EAAO,QAEP,EAOL,GAAa,EAA+B,IAAa,CAC7D,GAAI,OAAO,GAAQ,WACjB,OAAO,EAAI,EAAM,CACR,GAAQ,OACjB,EAAI,QAAU,IAIZ,GAAsC,GAAG,IACrC,GAAY,CAClB,IAAM,EAAW,EAAK,IAAK,GAAQ,EAAO,EAAK,EAAK,CAAC,CACrD,UACE,EAAS,SAAS,EAAS,IAAW,OAAO,GAAY,WAAa,GAAS,CAAG,EAAO,EAAK,GAAQ,KAAK,CAAE,EAI7G,GAAe,CAAE,SAAQ,WAAW,SAAU,WAAU,UAAS,eAAkC,CACvG,IAAM,EAAY,EAAuB,KAAK,CACxC,CAAC,EAAW,GAAgB,EAAyB,KAAK,CAE1D,EAAQ,EAAM,SAAS,IAAI,EAAW,GAAS,CACnD,GAAI,CAAC,EAAM,eAAe,EAAK,CAC7B,OAAO,KAET,IAAM,EAAc,EAAc,EAAK,CACvC,OAAO,EAAM,aAAa,EAAiC,CACzD,IAAK,EAAS,EAAc,GAAS,CAOnC,GAAQ,EAAU,SAAS,sBANP,CAClB,OAAQ,cACR,QAAS,aACT,OAAQ,YACR,MAAO,WACR,CAC4D,GAAW,EAAK,EAC7E,CACH,CAAC,EACF,CAEI,EAAS,MAAkB,CAC/B,EAAU,QAAU,EAAc,EAAO,CACzC,EACE,IAAa,WAAa,IAAa,SAAW,EAAU,QAAW,EAAU,SAAS,eAAiB,KAC5G,EACA,CAAC,EAAQ,EAAS,CAAC,CA4BtB,OA1BA,MAAsB,CACpB,GAAQ,CAER,IAAM,EAAW,IAAI,iBAAkB,GAAc,CAInD,CAHuB,EACpB,SAAS,CAAE,aAAY,kBAAmB,CAAC,GAAG,EAAY,GAAG,EAAa,CAAC,CAC3E,KAAM,GAAS,GAAW,SAAS,EAAK,CAAC,EACzB,GAAQ,EAC3B,CAMF,OAJA,EAAS,QAAQ,SAAS,KAAM,CAC9B,UAAW,GACX,QAAS,GACV,CAAC,KACW,EAAS,YAAY,EACjC,CAAC,EAAQ,EAAQ,EAAU,CAAC,CAE/B,MAAgB,CACd,GAAI,GAAa,EAAU,QAEzB,OADA,IAAU,EAAU,QAAS,EAAU,KAC1B,CACX,IAAY,EAAU,QAAU,EAAU,GAG7C,CAAC,EAAS,EAAW,EAAU,CAAC,CAE5B,GAAa,EAAa,EAAO,EAAU,EAGpD,EAAY,YAAc,cAE1B,IAAA,EAAe"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import React, { useEffect, useState, useRef, useCallback, useLayoutEffect } from 'react'\nimport { createPortal } from 'react-dom'\n\nexport interface MagicPortalProps {\n  anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null\n  position?: 'append' | 'prepend' | 'before' | 'after'\n  root?: Element\n  children?: React.ReactElement | React.ReactElement[]\n  onMount?: (anchor: Element, container: Element) => void\n  onUnmount?: (anchor: Element, container: Element) => void\n}\n\n/**\n * https://github.com/radix-ui/primitives/blob/36d954d3c1b41c96b1d2e875b93fc9362c8c09e6/packages/react/slot/src/slot.tsx#L166\n */\nconst getElementRef = (element: React.ReactElement) => {\n  // React <=18 in DEV\n  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get\n  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n  if (mayWarn) {\n    return (element as any).ref as React.Ref<Element>\n  }\n  // React 19 in DEV\n  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get\n  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning\n  if (mayWarn) {\n    return (element.props as { ref?: React.Ref<Element> }).ref\n  }\n\n  // Not DEV\n  return (element.props as { ref?: React.Ref<Element> }).ref || ((element as any).ref as React.Ref<Element>)\n}\n\nconst resolveAnchor = (anchor: MagicPortalProps['anchor']) => {\n  if (typeof anchor === 'string') {\n    return document.querySelector(anchor)\n  } else if (typeof anchor === 'function') {\n    return anchor()\n  } else if (anchor && 'current' in anchor) {\n    return anchor.current\n  } else {\n    return anchor\n  }\n}\n\nconst resolveContainer = (anchor: Element | null, position: MagicPortalProps['position']): Element | null => {\n  if (!anchor) {\n    return null\n  }\n\n  return position === 'prepend' || position === 'append' ? anchor : anchor.parentElement\n}\n\n/**\n * https://github.com/facebook/react/blob/d91d28c8ba6fe7c96e651f82fc47c9d5481bf5f9/packages/react-reconciler/src/ReactFiberHooks.js#L2792\n */\nconst setRef = <T>(ref: React.Ref<T> | undefined, value: T) => {\n  if (typeof ref === 'function') {\n    return ref(value)\n  } else if (ref !== null && ref !== undefined) {\n    ref.current = value\n  }\n}\n\nconst mergeRef = <T extends Element | null>(...refs: (React.Ref<T> | undefined)[]) => {\n  return (node: T) => {\n    const cleanups = refs.map((ref) => setRef(ref, node))\n    return () =>\n      cleanups.forEach((cleanup, index) => (typeof cleanup === 'function' ? cleanup() : setRef(refs[index], null)))\n  }\n}\n\nconst MagicPortal = ({\n  anchor,\n  position = 'append',\n  root = document.body,\n  children,\n  onMount,\n  onUnmount\n}: MagicPortalProps) => {\n  const anchorRef = useRef<Element | null>(null)\n  const [container, setContainer] = useState<Element | null>(null)\n\n  const insertNode = useCallback(\n    (node: Element | null) => {\n      if (!node) {\n        return\n      }\n\n      const anchorElement = anchorRef.current\n      if (!anchorElement) {\n        return\n      }\n\n      const containerElement = resolveContainer(anchorElement, position)\n      if (!containerElement) {\n        return\n      }\n\n      let alreadyPlaced = false\n\n      switch (position) {\n        case 'append':\n          alreadyPlaced = node.parentElement === containerElement && containerElement.lastChild === node\n          break\n        case 'prepend':\n          alreadyPlaced = node.parentElement === containerElement && containerElement.firstChild === node\n          break\n        case 'before':\n          alreadyPlaced = node.parentElement === containerElement && anchorElement.previousSibling === node\n          break\n        case 'after':\n          alreadyPlaced = node.parentElement === containerElement && anchorElement.nextSibling === node\n          break\n      }\n\n      if (!alreadyPlaced) {\n        const positionMap = {\n          before: 'beforebegin',\n          prepend: 'afterbegin',\n          append: 'beforeend',\n          after: 'afterend'\n        } as const\n        anchorElement.insertAdjacentElement(positionMap[position], node)\n      }\n    },\n    [position]\n  )\n\n  const nodes = React.Children.map(children, (item) => {\n    if (!React.isValidElement(item)) {\n      return null\n    }\n    const originalRef = getElementRef(item)\n    return React.cloneElement(item as React.ReactElement<any>, {\n      ref: mergeRef(originalRef, insertNode)\n    })\n  })\n\n  const update = useCallback(() => {\n    anchorRef.current = resolveAnchor(anchor)\n    const nextContainer = resolveContainer(anchorRef.current, position)\n    /**\n     * React 19 in DEV\n     * Suppress DevTools warning from React runtime about conflicting container children.\n     * @see https://github.com/facebook/react/blob/main/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js#L973\n     */\n    if (nextContainer) {\n      ;(nextContainer as { __reactWarnedAboutChildrenConflict?: boolean }).__reactWarnedAboutChildrenConflict = true\n    }\n\n    setContainer(nextContainer)\n  }, [anchor, position])\n\n  useLayoutEffect(() => {\n    update()\n\n    const observer = new MutationObserver((mutations) => {\n      const isSelfMutation = mutations\n        .flatMap(({ addedNodes, removedNodes }) => [...addedNodes, ...removedNodes])\n        .some((node) => container?.contains(node))\n      !isSelfMutation && update()\n    })\n\n    observer.observe(root, {\n      childList: true,\n      subtree: true\n    })\n    return () => observer.disconnect()\n  }, [update, anchor, container, root])\n\n  useEffect(() => {\n    if (container && anchorRef.current) {\n      onMount?.(anchorRef.current, container)\n      return () => {\n        onUnmount?.(anchorRef.current!, container)\n      }\n    }\n  }, [onMount, onUnmount, container])\n\n  return container ? createPortal(nodes, container) : null\n}\n\nMagicPortal.displayName = 'MagicPortal'\n\nexport default MagicPortal\n"],"mappings":"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"}

package/packages/component/eslint.config.ts

@@ -1,12 +1,12 @@
 import globals from 'globals'
+import type { Linter } from 'eslint'
 import pluginJs from '@eslint/js'
 import { defineConfig } from 'eslint/config'
 import tseslint from 'typescript-eslint'
 import prettierPlugin from 'eslint-plugin-prettier/recommended'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
+import eslintReact from '@eslint-react/eslint-plugin'
 
-export default defineConfig([
+const config: Linter.FlatConfig[] = defineConfig([
   {
     ignores: ['**/dist/*']
   },
@@ -18,14 +18,18 @@ export default defineConfig([
     }
   },
   pluginJs.configs.recommended,
-  ...tseslint.configs.recommended,
+  tseslint.configs.recommended,
+  eslintReact.configs['recommended-typescript'],
   prettierPlugin,
-  reactHooks.configs['recommended-latest'],
-  reactRefresh.configs.vite,
   {
     rules: {
       '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/no-unused-expressions': 'off'
+      '@typescript-eslint/no-unused-expressions': 'off',
+      '@eslint-react/no-children-map': 'off',
+      '@eslint-react/no-clone-element': 'off',
+      '@eslint-react/hooks-extra/no-direct-set-state-in-use-effect': 'off'
     }
   }
 ])
+
+export default config

package/packages/component/package.json

@@ -29,22 +29,21 @@
   },
   "homepage": "https://github.com/molvqingtai/react-magic-portal#readme",
   "devDependencies": {
-    "@eslint/js": "^9.36.0",
-    "@types/node": "^24.6.0",
-    "@types/react": "^19.1.15",
-    "@types/react-dom": "^19.1.9",
-    "eslint": "^9.36.0",
+    "@eslint-react/eslint-plugin": "^2.0.6",
+    "@eslint/js": "^9.37.0",
+    "@types/node": "^24.7.1",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.1",
+    "eslint": "^9.37.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-react-hooks": "^5.2.0",
-    "eslint-plugin-react-refresh": "^0.4.22",
     "globals": "^16.4.0",
     "prettier": "^3.6.2",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "tsdown": "^0.15.5",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.45.0"
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tsdown": "^0.15.6",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

package/packages/component/src/index.ts

@@ -4,6 +4,7 @@ import { createPortal } from 'react-dom'
 export interface MagicPortalProps {
   anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null
   position?: 'append' | 'prepend' | 'before' | 'after'
+  root?: Element
   children?: React.ReactElement | React.ReactElement[]
   onMount?: (anchor: Element, container: Element) => void
   onUnmount?: (anchor: Element, container: Element) => void
@@ -42,6 +43,14 @@ const resolveAnchor = (anchor: MagicPortalProps['anchor']) => {
   }
 }
 
+const resolveContainer = (anchor: Element | null, position: MagicPortalProps['position']): Element | null => {
+  if (!anchor) {
+    return null
+  }
+
+  return position === 'prepend' || position === 'append' ? anchor : anchor.parentElement
+}
+
 /**
  * https://github.com/facebook/react/blob/d91d28c8ba6fe7c96e651f82fc47c9d5481bf5f9/packages/react-reconciler/src/ReactFiberHooks.js#L2792
  */
@@ -61,33 +70,86 @@ const mergeRef = <T extends Element | null>(...refs: (React.Ref<T> | undefined)[
   }
 }
 
-const MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount }: MagicPortalProps) => {
+const MagicPortal = ({
+  anchor,
+  position = 'append',
+  root = document.body,
+  children,
+  onMount,
+  onUnmount
+}: MagicPortalProps) => {
   const anchorRef = useRef<Element | null>(null)
   const [container, setContainer] = useState<Element | null>(null)
 
-  const nodes = React.Children.map(children, (item) => {
-    if (!React.isValidElement(item)) {
-      return null
-    }
-    const originalRef = getElementRef(item)
-    return React.cloneElement(item as React.ReactElement<any>, {
-      ref: mergeRef(originalRef, (node) => {
+  const insertNode = useCallback(
+    (node: Element | null) => {
+      if (!node) {
+        return
+      }
+
+      const anchorElement = anchorRef.current
+      if (!anchorElement) {
+        return
+      }
+
+      const containerElement = resolveContainer(anchorElement, position)
+      if (!containerElement) {
+        return
+      }
+
+      let alreadyPlaced = false
+
+      switch (position) {
+        case 'append':
+          alreadyPlaced = node.parentElement === containerElement && containerElement.lastChild === node
+          break
+        case 'prepend':
+          alreadyPlaced = node.parentElement === containerElement && containerElement.firstChild === node
+          break
+        case 'before':
+          alreadyPlaced = node.parentElement === containerElement && anchorElement.previousSibling === node
+          break
+        case 'after':
+          alreadyPlaced = node.parentElement === containerElement && anchorElement.nextSibling === node
+          break
+      }
+
+      if (!alreadyPlaced) {
         const positionMap = {
           before: 'beforebegin',
           prepend: 'afterbegin',
           append: 'beforeend',
           after: 'afterend'
         } as const
-        node && anchorRef.current?.insertAdjacentElement(positionMap[position], node)
-      })
+        anchorElement.insertAdjacentElement(positionMap[position], node)
+      }
+    },
+    [position]
+  )
+
+  const nodes = React.Children.map(children, (item) => {
+    if (!React.isValidElement(item)) {
+      return null
+    }
+    const originalRef = getElementRef(item)
+    return React.cloneElement(item as React.ReactElement<any>, {
+      ref: mergeRef(originalRef, insertNode)
     })
   })
 
   const update = useCallback(() => {
     anchorRef.current = resolveAnchor(anchor)
-    setContainer(
-      position === 'prepend' || position === 'append' ? anchorRef.current : (anchorRef.current?.parentElement ?? null)
-    )
+    const nextContainer = resolveContainer(anchorRef.current, position)
+    /**
+     * React 19 in DEV
+     * Suppress DevTools warning from React runtime about conflicting container children.
+     * @see https://github.com/facebook/react/blob/main/packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js#L973
+     */
+    if (nextContainer) {
+      ;(nextContainer as { __reactWarnedAboutChildrenConflict?: boolean }).__reactWarnedAboutChildrenConflict = true
+    }
+
+    setContainer(nextContainer)
   }, [anchor, position])
 
   useLayoutEffect(() => {
@@ -100,12 +162,12 @@ const MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount
       !isSelfMutation && update()
     })
 
-    observer.observe(document.body, {
+    observer.observe(root, {
       childList: true,
       subtree: true
     })
     return () => observer.disconnect()
-  }, [update, anchor, container])
+  }, [update, anchor, container, root])
 
   useEffect(() => {
     if (container && anchorRef.current) {
@@ -116,7 +178,7 @@ const MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount
     }
   }, [onMount, onUnmount, container])
 
-  return container && createPortal(nodes, container)
+  return container ? createPortal(nodes, container) : null
 }
 
 MagicPortal.displayName = 'MagicPortal'