react-magic-portal 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.3.1](https://github.com/molvqingtai/react-magic-portal/compare/v1.3.0...v1.3.1) (2025-11-07)
+
+
+### Performance Improvements
+
+* better position name ([af11ae6](https://github.com/molvqingtai/react-magic-portal/commit/af11ae67e1bf8998067d0cf756128b279ea1f385))
+
+# [1.3.0](https://github.com/molvqingtai/react-magic-portal/compare/v1.2.1...v1.3.0) (2025-10-10)
+
+
+### Features
+
+* enforce single child ([8fe438d](https://github.com/molvqingtai/react-magic-portal/commit/8fe438d149a04d3070fe8eed725d7932492da01c))
+
 ## [1.2.1](https://github.com/molvqingtai/react-magic-portal/compare/v1.2.0...v1.2.1) (2025-10-10)
 
 

package/README.md

@@ -26,7 +26,7 @@ React Magic Portal solves these challenges by automatically detecting when targe
 ## Features
 
 - **Dynamic Anchor Detection** - Automatically detects when target elements appear or disappear in the DOM
-- **Multiple Positioning Options** - Support for `append`, `prepend`, `before`, and `after` positioning
+- **Multiple Positioning Options** - Support for `last`, `first`, `before`, and `after` positioning
 - **Flexible Anchor Selection** - Support for CSS selectors, element references, functions, and direct elements
 - **Lifecycle Callbacks** - `onMount` and `onUnmount` callbacks for portal lifecycle management
 - **TypeScript Support** - Full TypeScript support with comprehensive type definitions
@@ -77,11 +77,11 @@ function App() {
         <div>Content before target</div>
       </MagicPortal>
 
-      <MagicPortal anchor="#target" position="prepend">
+      <MagicPortal anchor="#target" position="first">
         <div>Content at start of target</div>
       </MagicPortal>
 
-      <MagicPortal anchor="#target" position="append">
+      <MagicPortal anchor="#target" position="last">
         <div>Content at end of target</div>
       </MagicPortal>
 
@@ -100,9 +100,9 @@ function App() {
 | 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                      |
+| `position`  | `'last' \| 'first' \| 'before' \| 'after'`                                             | `'last'`      | 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                          |
+| `children`  | `React.ReactElement \| null`                                               | `undefined`     | A single React element to render in the portal (does not support Fragment)                          |
 | `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                  |
 
@@ -150,7 +150,7 @@ const elementRef = useRef(null)
 
 ### Position Options
 
-#### `append` (default)
+#### `last` (default)
 
 Adds content inside the anchor element at the end:
 
@@ -161,7 +161,7 @@ Adds content inside the anchor element at the end:
 </div>
 ```
 
-#### `prepend`
+#### `first`
 
 Adds content inside the anchor element at the beginning:
 

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

@@ -191,7 +191,7 @@ describe('MagicPortal', () => {
       document.body.appendChild(anchor)
     })
 
-    it('should append by default', () => {
+    it('should last by default', () => {
       render(
         <MagicPortal anchor="#position-anchor">
           <div data-testid="portal-content">Portal Content</div>
@@ -204,9 +204,9 @@ describe('MagicPortal', () => {
       expect(anchor.contains(portalContent)).toBe(true)
     })
 
-    it('should prepend when position is prepend', () => {
+    it('should first when position is first', () => {
       render(
-        <MagicPortal anchor="#position-anchor" position="prepend">
+        <MagicPortal anchor="#position-anchor" position="first">
           <div data-testid="portal-content">Portal Content</div>
         </MagicPortal>
       )
@@ -382,28 +382,6 @@ describe('MagicPortal', () => {
       expect(refCallback).toHaveBeenLastCalledWith(null)
     })
 
-    it('should handle multiple content elements with refs', () => {
-      const ref1 = vi.fn()
-      const ref2 = vi.fn()
-      const anchor = document.createElement('div')
-      anchor.id = 'multi-ref-anchor'
-      document.body.appendChild(anchor)
-
-      render(
-        <MagicPortal anchor="#multi-ref-anchor">
-          <div ref={ref1} data-testid="content-1">
-            Content 1
-          </div>
-          <span ref={ref2} data-testid="content-2">
-            Content 2
-          </span>
-        </MagicPortal>
-      )
-
-      expect(ref1).toHaveBeenCalledWith(expect.any(HTMLDivElement))
-      expect(ref2).toHaveBeenCalledWith(expect.any(HTMLSpanElement))
-    })
-
     it('should maintain content refs across position changes', async () => {
       const contentRef = vi.fn()
       const anchor = document.createElement('div')
@@ -411,7 +389,7 @@ describe('MagicPortal', () => {
       document.body.appendChild(anchor)
 
       const { rerender } = render(
-        <MagicPortal anchor="#position-ref-anchor" position="append">
+        <MagicPortal anchor="#position-ref-anchor" position="last">
           <div ref={contentRef} data-testid="portal-content">
             Portal Content
           </div>
@@ -425,7 +403,7 @@ describe('MagicPortal', () => {
       contentRef.mockClear()
 
       rerender(
-        <MagicPortal anchor="#position-ref-anchor" position="prepend">
+        <MagicPortal anchor="#position-ref-anchor" position="first">
           <div ref={contentRef} data-testid="portal-content">
             Portal Content
           </div>
@@ -466,43 +444,26 @@ describe('MagicPortal', () => {
       expect(refCalls[0]?.textContent).toBe('Click me')
     })
 
-    it('should handle single element content', () => {
+    it('should log error when multiple children are provided', () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
       const anchor = document.createElement('div')
-      anchor.id = 'single-content-anchor'
+      anchor.id = 'multiple-children-anchor'
       document.body.appendChild(anchor)
 
       render(
-        <MagicPortal anchor="#single-content-anchor">
-          <span data-testid="single-content">Just content</span>
+        // @ts-expect-error - intentionally passing multiple children to assert runtime guard
+        <MagicPortal anchor="#multiple-children-anchor">
+          <span data-testid="first-element">First element</span>
+          <span data-testid="second-element">Second element</span>
         </MagicPortal>
       )
 
-      expect(screen.getByTestId('single-content')).toBeTruthy()
-      expect(anchor.contains(screen.getByTestId('single-content'))).toBe(true)
-    })
-
-    it('should handle multiple element content with refs', () => {
-      const ref1 = vi.fn()
-      const ref2 = vi.fn()
-      const anchor = document.createElement('div')
-      anchor.id = 'multiple-content-anchor'
-      document.body.appendChild(anchor)
-
-      render(
-        <MagicPortal anchor="#multiple-content-anchor">
-          <span ref={ref1} data-testid="first-element">
-            First element
-          </span>
-          <div ref={ref2} data-testid="second-element">
-            Second element
-          </div>
-        </MagicPortal>
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '[react-magic-portal] Multiple children are not supported, expected to receive a single React element child.'
       )
+      expect(anchor.children.length).toBe(0)
 
-      expect(ref1).toHaveBeenCalledWith(expect.any(HTMLSpanElement))
-      expect(ref2).toHaveBeenCalledWith(expect.any(HTMLDivElement))
-      expect(screen.getByTestId('first-element')).toBeTruthy()
-      expect(screen.getByTestId('second-element')).toBeTruthy()
+      consoleErrorSpy.mockRestore()
     })
 
     it('should handle nested refs correctly', () => {
@@ -583,10 +544,10 @@ describe('MagicPortal', () => {
 
       render(
         <div>
-          <MagicPortal anchor="#multi-anchor" position="prepend">
+          <MagicPortal anchor="#multi-anchor" position="first">
             <div data-testid="portal-1">Portal 1</div>
           </MagicPortal>
-          <MagicPortal anchor="#multi-anchor" position="append">
+          <MagicPortal anchor="#multi-anchor" position="last">
             <div data-testid="portal-2">Portal 2</div>
           </MagicPortal>
         </div>
@@ -707,61 +668,56 @@ describe('MagicPortal', () => {
   })
 
   describe('Text Node Handling', () => {
-    it('should not render pure text content', () => {
+    it('should not render Fragment children', () => {
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
       const anchor = document.createElement('div')
-      anchor.id = 'text-only-anchor'
+      anchor.id = 'fragment-anchor'
       document.body.appendChild(anchor)
 
       render(
-        // @ts-expect-error - testing that text nodes are not rendered
-        <MagicPortal anchor="#text-only-anchor">Just plain text</MagicPortal>
+        <MagicPortal anchor="#fragment-anchor">
+          <>
+            <div>Child 1</div>
+            <div>Child 2</div>
+          </>
+        </MagicPortal>
       )
 
-      // Anchor should remain empty since text nodes are not rendered
+      // Should log error about Fragment not being supported
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '[react-magic-portal] Fragment children are not supported, expected to receive a single React element child.'
+      )
+
+      // Anchor should remain empty since Fragment is not supported
       expect(anchor.textContent).toBe('')
       expect(anchor.children.length).toBe(0)
+
+      consoleErrorSpy.mockRestore()
     })
 
-    it('should not render mixed text and element content (only elements)', () => {
+    it('should not render pure text content', () => {
       const anchor = document.createElement('div')
-      anchor.id = 'mixed-text-anchor'
+      anchor.id = 'text-only-anchor'
       document.body.appendChild(anchor)
 
       render(
-        // @ts-expect-error - testing mixed content behavior
-        <MagicPortal anchor="#mixed-text-anchor">
-          Some text before
-          {/* @ts-expect-error - testing mixed content behavior*/}
-          <div data-testid="element-content">Element</div>
-          Some text after
-        </MagicPortal>
+        // @ts-expect-error - testing that text nodes are not rendered
+        <MagicPortal anchor="#text-only-anchor">Just plain text</MagicPortal>
       )
 
-      // Only the div element should be rendered, text nodes should be ignored
-      expect(screen.getByTestId('element-content')).toBeTruthy()
-      expect(anchor.contains(screen.getByTestId('element-content'))).toBe(true)
-
-      // Text content should only be from the div element, not the text nodes
-      expect(anchor.textContent?.trim()).toBe('Element')
-      expect(anchor.textContent).not.toContain('Some text before')
-      expect(anchor.textContent).not.toContain('Some text after')
+      // Anchor should remain empty since text nodes are not rendered
+      expect(anchor.textContent).toBe('')
+      expect(anchor.children.length).toBe(0)
     })
 
-    it('should not render number or boolean primitives', () => {
+    it('should not render null children', () => {
       const anchor = document.createElement('div')
-      anchor.id = 'primitive-anchor'
+      anchor.id = 'null-anchor'
       document.body.appendChild(anchor)
 
-      render(
-        <MagicPortal anchor="#primitive-anchor">
-          {42 as any}
-          {true as any}
-          {null as any}
-          {undefined as any}
-        </MagicPortal>
-      )
+      render(<MagicPortal anchor="#null-anchor">{null}</MagicPortal>)
 
-      // Anchor should remain empty since primitives are not rendered
+      // Anchor should remain empty since null is not rendered
       expect(anchor.textContent).toBe('')
       expect(anchor.children.length).toBe(0)
     })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-magic-portal",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "React Portal with dynamic mounting support",
   "main": "packages/component/dist/index.js",
   "type": "module",

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

@@ -3,9 +3,9 @@ import React from "react";
 //#region src/index.d.ts
 interface MagicPortalProps {
   anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null;
-  position?: 'append' | 'prepend' | 'before' | 'after';
+  position?: 'last' | 'first' | 'before' | 'after';
   root?: Element;
-  children?: React.ReactElement | React.ReactElement[];
+  children?: React.ReactElement | null;
   onMount?: (anchor: Element, container: Element) => void;
   onUnmount?: (anchor: Element, container: Element) => void;
 }

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,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"}
+{"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,MAAA,GAAgB,OAAA,GAAA,QAAA,GAAA,OAAA;EAAA,IAAA,CAAA,EAGxB,OAHwB;UACP,CAAA,EAGb,KAAA,CAAM,YAHO,GAAA,IAAA;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;aACE,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)=>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};
+import e,{useCallback as t,useEffect as n,useLayoutEffect as r,useMemo as i,useRef as a,useState as o}from"react";import{createPortal as s}from"react-dom";const c=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)},l=e=>typeof e==`string`?document.querySelector(e):typeof e==`function`?e():e&&`current`in e?e.current:e,u=(e,t)=>e?t===`first`||t===`last`?e:e.parentElement:null,d=(e,t)=>{if(typeof e==`function`)return e(t);e!=null&&(e.current=t)},f=(...e)=>t=>{let n=e.map(e=>d(e,t));return()=>n.forEach((t,n)=>typeof t==`function`?t():d(e[n],null))},p=({anchor:d,position:p=`last`,root:m=document.body,children:h,onMount:g,onUnmount:_})=>{let v=a(null),[y,b]=o(null),x=t(e=>{if(!e)return;let t=v.current;if(!t)return;let n=u(t,p);if(!n)return;let r=!1;switch(p){case`last`:r=e.parentElement===n&&n.lastChild===e;break;case`first`: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`,first:`afterbegin`,last:`beforeend`,after:`afterend`}[p],e)},[p]),S=i(()=>{if(e.Children.count(h)>1)return console.error(`[react-magic-portal] Multiple children are not supported, expected to receive a single React element child.`),null;if(!e.isValidElement(h))return null;if(h.type===e.Fragment)return console.error(`[react-magic-portal] Fragment children are not supported, expected to receive a single React element child.`),null;let t=c(h);return e.cloneElement(h,{ref:f(t,x)})},[h,x]),C=t(()=>{v.current=l(d);let e=u(v.current,p);e&&(e.__reactWarnedAboutChildrenConflict=!0),b(e)},[d,p]);return r(()=>{C();let e=new MutationObserver(e=>{!e.flatMap(({addedNodes:e,removedNodes:t})=>[...e,...t]).some(e=>y?.contains(e))&&C()});return e.observe(m,{childList:!0,subtree:!0}),()=>e.disconnect()},[C,d,y,m]),n(()=>{if(y&&v.current)return g?.(v.current,y),()=>{_?.(v.current,y)}},[g,_,y]),y&&S?s(S,y):null};p.displayName=`MagicPortal`;var m=p;export{m 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  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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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import React, { useEffect, useState, useRef, useCallback, useLayoutEffect, useMemo } from 'react'\nimport { createPortal } from 'react-dom'\n\nexport interface MagicPortalProps {\n  anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null\n  position?: 'last' | 'first' | 'before' | 'after'\n  root?: Element\n  children?: React.ReactElement | null\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 === 'first' || position === 'last' ? 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 = 'last',\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 'last':\n          alreadyPlaced = node.parentElement === containerElement && containerElement.lastChild === node\n          break\n        case 'first':\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          first: 'afterbegin',\n          last: 'beforeend',\n          after: 'afterend'\n        } as const\n        anchorElement.insertAdjacentElement(positionMap[position], node)\n      }\n    },\n    [position]\n  )\n\n  const child = useMemo(() => {\n    if (React.Children.count(children) > 1) {\n      console.error(\n        '[react-magic-portal] Multiple children are not supported, expected to receive a single React element child.'\n      )\n      return null\n    }\n\n    if (!React.isValidElement(children)) {\n      return null\n    }\n\n    if (children.type === React.Fragment) {\n      console.error(\n        '[react-magic-portal] Fragment children are not supported, expected to receive a single React element child.'\n      )\n      return null\n    }\n\n    const originalRef = getElementRef(children)\n    return React.cloneElement(children as React.ReactElement<any>, {\n      ref: mergeRef(originalRef, insertNode)\n    })\n  }, [children, insertNode])\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 && child ? createPortal(child, container) : null\n}\n\nMagicPortal.displayName = 'MagicPortal'\n\nexport default MagicPortal\n"],"mappings":"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"}

package/packages/component/eslint.config.ts

@@ -27,6 +27,8 @@ const config: Linter.FlatConfig[] = defineConfig([
       '@typescript-eslint/no-unused-expressions': 'off',
       '@eslint-react/no-children-map': 'off',
       '@eslint-react/no-clone-element': 'off',
+      '@eslint-react/no-children-only': 'off',
+      '@eslint-react/no-children-count': 'off',
       '@eslint-react/hooks-extra/no-direct-set-state-in-use-effect': 'off'
     }
   }

package/packages/component/src/index.ts

@@ -1,11 +1,11 @@
-import React, { useEffect, useState, useRef, useCallback, useLayoutEffect } from 'react'
+import React, { useEffect, useState, useRef, useCallback, useLayoutEffect, useMemo } from 'react'
 import { createPortal } from 'react-dom'
 
 export interface MagicPortalProps {
   anchor: string | (() => Element | null) | Element | React.RefObject<Element | null> | null
-  position?: 'append' | 'prepend' | 'before' | 'after'
+  position?: 'last' | 'first' | 'before' | 'after'
   root?: Element
-  children?: React.ReactElement | React.ReactElement[]
+  children?: React.ReactElement | null
   onMount?: (anchor: Element, container: Element) => void
   onUnmount?: (anchor: Element, container: Element) => void
 }
@@ -48,7 +48,7 @@ const resolveContainer = (anchor: Element | null, position: MagicPortalProps['po
     return null
   }
 
-  return position === 'prepend' || position === 'append' ? anchor : anchor.parentElement
+  return position === 'first' || position === 'last' ? anchor : anchor.parentElement
 }
 
 /**
@@ -72,7 +72,7 @@ const mergeRef = <T extends Element | null>(...refs: (React.Ref<T> | undefined)[
 
 const MagicPortal = ({
   anchor,
-  position = 'append',
+  position = 'last',
   root = document.body,
   children,
   onMount,
@@ -100,10 +100,10 @@ const MagicPortal = ({
       let alreadyPlaced = false
 
       switch (position) {
-        case 'append':
+        case 'last':
           alreadyPlaced = node.parentElement === containerElement && containerElement.lastChild === node
           break
-        case 'prepend':
+        case 'first':
           alreadyPlaced = node.parentElement === containerElement && containerElement.firstChild === node
           break
         case 'before':
@@ -117,8 +117,8 @@ const MagicPortal = ({
       if (!alreadyPlaced) {
         const positionMap = {
           before: 'beforebegin',
-          prepend: 'afterbegin',
-          append: 'beforeend',
+          first: 'afterbegin',
+          last: 'beforeend',
           after: 'afterend'
         } as const
         anchorElement.insertAdjacentElement(positionMap[position], node)
@@ -127,15 +127,30 @@ const MagicPortal = ({
     [position]
   )
 
-  const nodes = React.Children.map(children, (item) => {
-    if (!React.isValidElement(item)) {
+  const child = useMemo(() => {
+    if (React.Children.count(children) > 1) {
+      console.error(
+        '[react-magic-portal] Multiple children are not supported, expected to receive a single React element child.'
+      )
       return null
     }
-    const originalRef = getElementRef(item)
-    return React.cloneElement(item as React.ReactElement<any>, {
+
+    if (!React.isValidElement(children)) {
+      return null
+    }
+
+    if (children.type === React.Fragment) {
+      console.error(
+        '[react-magic-portal] Fragment children are not supported, expected to receive a single React element child.'
+      )
+      return null
+    }
+
+    const originalRef = getElementRef(children)
+    return React.cloneElement(children as React.ReactElement<any>, {
       ref: mergeRef(originalRef, insertNode)
     })
-  })
+  }, [children, insertNode])
 
   const update = useCallback(() => {
     anchorRef.current = resolveAnchor(anchor)
@@ -178,7 +193,7 @@ const MagicPortal = ({
     }
   }, [onMount, onUnmount, container])
 
-  return container ? createPortal(nodes, container) : null
+  return container && child ? createPortal(child, container) : null
 }
 
 MagicPortal.displayName = 'MagicPortal'