react-magic-portal 1.1.3 → 1.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +75 -0
- package/__tests__/eslint.config.ts +1 -1
- package/package.json +1 -1
- package/packages/component/dist/index.js +1 -1
- package/packages/component/dist/index.js.map +1 -1
- package/packages/component/eslint.config.ts +1 -1
- package/packages/component/src/index.ts +8 -21
- package/packages/example/dist/assets/index-BeXVndGe.js +49 -0
- package/packages/example/dist/index.html +1 -1
- package/packages/example/eslint.config.ts +1 -1
- package/packages/example/src/components/portal-content.tsx +7 -2
- package/packages/example/dist/assets/index-BXJSx7fv.js +0 -49
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,17 @@
|
|
|
1
|
+
## [1.1.5](https://github.com/molvqingtai/react-magic-portal/compare/v1.1.4...v1.1.5) (2025-09-26)
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
### Performance Improvements
|
|
5
|
+
|
|
6
|
+
* expand the anchor point mutation detection range ([110229f](https://github.com/molvqingtai/react-magic-portal/commit/110229f438cff2674625ab49438b9cb41eab76ee))
|
|
7
|
+
|
|
8
|
+
## [1.1.4](https://github.com/molvqingtai/react-magic-portal/compare/v1.1.3...v1.1.4) (2025-09-26)
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
### Performance Improvements
|
|
12
|
+
|
|
13
|
+
* add ref forward notes ([4e36266](https://github.com/molvqingtai/react-magic-portal/commit/4e36266df2724c2c463e8877fd9d424c796aa6da))
|
|
14
|
+
|
|
1
15
|
## [1.1.3](https://github.com/molvqingtai/react-magic-portal/compare/v1.1.2...v1.1.3) (2025-09-25)
|
|
2
16
|
|
|
3
17
|
|
package/README.md
CHANGED
|
@@ -190,6 +190,81 @@ Adds content as a sibling after the anchor element:
|
|
|
190
190
|
<!-- Portal content appears here -->
|
|
191
191
|
```
|
|
192
192
|
|
|
193
|
+
## Important Notes
|
|
194
|
+
|
|
195
|
+
### React Component Ref Requirements
|
|
196
|
+
|
|
197
|
+
When using React components as children, they **must** support ref forwarding to work correctly with MagicPortal. This is because MagicPortal needs to access the underlying DOM element to position it correctly.
|
|
198
|
+
|
|
199
|
+
#### ✅ Works - Components with ref props (React 19+)
|
|
200
|
+
|
|
201
|
+
```jsx
|
|
202
|
+
interface MyComponentProps {
|
|
203
|
+
ref?: React.Ref<HTMLDivElement>
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
const MyComponent = ({ ref, ...props }: MyComponentProps) => {
|
|
207
|
+
return <div ref={ref}>My Component Content</div>
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
// This will work correctly
|
|
211
|
+
<MagicPortal anchor="#target">
|
|
212
|
+
<MyComponent />
|
|
213
|
+
</MagicPortal>
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
#### ✅ Works - Components with forwardRef (React 18 and earlier)
|
|
217
|
+
|
|
218
|
+
```jsx
|
|
219
|
+
import { forwardRef } from 'react'
|
|
220
|
+
|
|
221
|
+
const MyComponent = forwardRef<HTMLDivElement>((props, ref) => {
|
|
222
|
+
return <div ref={ref}>My Component Content</div>
|
|
223
|
+
})
|
|
224
|
+
|
|
225
|
+
// This will work correctly
|
|
226
|
+
<MagicPortal anchor="#target">
|
|
227
|
+
<MyComponent />
|
|
228
|
+
</MagicPortal>
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
#### ✅ Works - Direct DOM elements
|
|
232
|
+
|
|
233
|
+
```jsx
|
|
234
|
+
// Direct DOM elements always work
|
|
235
|
+
<MagicPortal anchor="#target">
|
|
236
|
+
<div>Direct DOM element</div>
|
|
237
|
+
</MagicPortal>
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
#### ❌ Won't work - Components without ref support
|
|
241
|
+
|
|
242
|
+
```jsx
|
|
243
|
+
const MyComponent = () => {
|
|
244
|
+
return <div>My Component Content</div>
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
// This won't position correctly because ref cannot be passed to the component
|
|
248
|
+
<MagicPortal anchor="#target">
|
|
249
|
+
<MyComponent />
|
|
250
|
+
</MagicPortal>
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
#### ✅ Solution - Wrap with DOM element
|
|
254
|
+
|
|
255
|
+
```jsx
|
|
256
|
+
const MyComponent = () => {
|
|
257
|
+
return <div>My Component Content</div>
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
// Wrap the component in a transparent DOM element
|
|
261
|
+
<MagicPortal anchor="#target">
|
|
262
|
+
<div style={{ display: 'contents' }}>
|
|
263
|
+
<MyComponent />
|
|
264
|
+
</div>
|
|
265
|
+
</MagicPortal>
|
|
266
|
+
```
|
|
267
|
+
|
|
193
268
|
## License
|
|
194
269
|
|
|
195
270
|
MIT © [molvqingtai](https://github.com/molvqingtai)
|
|
@@ -11,7 +11,7 @@ export default defineConfig([
|
|
|
11
11
|
ignores: ['**/dist/*']
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
|
-
files: ['**/*.{js,mjs,cjs,ts}'],
|
|
14
|
+
files: ['**/*.{js,jsx,mjs,cjs,ts,tsx}'],
|
|
15
15
|
languageOptions: {
|
|
16
16
|
globals: { ...globals.browser, ...globals.node },
|
|
17
17
|
parserOptions: { project: './tsconfig.json', tsconfigRootDir: import.meta.dirname }
|
package/package.json
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import e,{useCallback as t,useEffect as n,useLayoutEffect as r,useRef as i,useState as a}from"react";import 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.forEach(e=>{typeof e==`function`?e(t):e&&(e.current=t)}),u=({anchor:u,position:d=`append`,children:f,onMount:p,onUnmount:m,key:h})=>{let g=i(null),[_,v]=a(null),y=e.Children.map(f,t=>{if(!e.isValidElement(t))return null;let n=s(t);return e.cloneElement(t,{ref:l(n,e=>{e&&g.current?.insertAdjacentElement({before:`beforebegin`,prepend:`afterbegin`,append:`beforeend`,after:`afterend`}[d],e)})})}),b=t(()=>{g.current=c(u)
|
|
1
|
+
import e,{useCallback as t,useEffect as n,useLayoutEffect as r,useRef as i,useState as a}from"react";import 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.forEach(e=>{typeof e==`function`?e(t):e&&(e.current=t)}),u=({anchor:u,position:d=`append`,children:f,onMount:p,onUnmount:m,key:h})=>{let g=i(null),[_,v]=a(null),y=e.Children.map(f,t=>{if(!e.isValidElement(t))return null;let n=s(t);return e.cloneElement(t,{ref:l(n,e=>{e&&g.current?.insertAdjacentElement({before:`beforebegin`,prepend:`afterbegin`,append:`beforeend`,after:`afterend`}[d],e)})})}),b=t(()=>{g.current=c(u),v(d===`prepend`||d===`append`?g.current:g.current?.parentElement??null)},[u,d]);return r(()=>{b();let e=new MutationObserver(e=>{!e.flatMap(({addedNodes:e,removedNodes:t})=>[...e,...t]).some(e=>_?.contains(e))&&b()});return e.observe(document.body,{childList:!0,subtree:!0}),()=>e.disconnect()},[b,u,_]),n(()=>{if(_&&g.current)return p?.(g.current,_),()=>{m?.(g.current,_)}},[p,m,_]),_&&o.createPortal(y,_,h)};u.displayName=`MagicPortal`;var d=u;export{d as default};
|
|
2
2
|
//# sourceMappingURL=index.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","names":[
|
|
1
|
+
{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import React, { useEffect, useState, useRef, useCallback, useLayoutEffect } from 'react'\nimport ReactDOM 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 key?: React.Key\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 mergeRef = <T extends Element | null>(...refs: (React.Ref<T> | undefined)[]) => {\n return (node: T) =>\n refs.forEach((ref) => {\n if (typeof ref === 'function') {\n ref(node)\n } else if (ref) {\n ref.current = node\n }\n })\n}\n\nconst MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount, key }: 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 && ReactDOM.createPortal(nodes, container, key)\n}\n\nMagicPortal.displayName = 'MagicPortal'\n\nexport default MagicPortal\n"],"mappings":"8HAeA,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,EAIL,GAAsC,GAAG,IACrC,GACN,EAAK,QAAS,GAAQ,CAChB,OAAO,GAAQ,WACjB,EAAI,EAAK,CACA,IACT,EAAI,QAAU,IAEhB,CAGA,GAAe,CAAE,SAAQ,WAAW,SAAU,WAAU,UAAS,YAAW,SAA4B,CAC5G,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,EAAS,aAAa,EAAO,EAAW,EAAI,EAGlE,EAAY,YAAc,cAE1B,IAAA,EAAe"}
|
|
@@ -11,7 +11,7 @@ export default defineConfig([
|
|
|
11
11
|
ignores: ['**/dist/*']
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
|
-
files: ['**/*.{js,mjs,cjs,ts}'],
|
|
14
|
+
files: ['**/*.{js,jsx,mjs,cjs,ts,tsx}'],
|
|
15
15
|
languageOptions: {
|
|
16
16
|
globals: { ...globals.browser, ...globals.node },
|
|
17
17
|
parserOptions: { project: './tsconfig.json', tsconfigRootDir: import.meta.dirname }
|
|
@@ -64,7 +64,7 @@ const MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount
|
|
|
64
64
|
}
|
|
65
65
|
const originalRef = getElementRef(item)
|
|
66
66
|
return React.cloneElement(item as React.ReactElement<any>, {
|
|
67
|
-
ref: mergeRef(originalRef, (node
|
|
67
|
+
ref: mergeRef(originalRef, (node) => {
|
|
68
68
|
const positionMap = {
|
|
69
69
|
before: 'beforebegin',
|
|
70
70
|
prepend: 'afterbegin',
|
|
@@ -78,40 +78,27 @@ const MagicPortal = ({ anchor, position = 'append', children, onMount, onUnmount
|
|
|
78
78
|
|
|
79
79
|
const update = useCallback(() => {
|
|
80
80
|
anchorRef.current = resolveAnchor(anchor)
|
|
81
|
-
|
|
81
|
+
setContainer(
|
|
82
82
|
position === 'prepend' || position === 'append' ? anchorRef.current : (anchorRef.current?.parentElement ?? null)
|
|
83
|
-
|
|
83
|
+
)
|
|
84
84
|
}, [anchor, position])
|
|
85
85
|
|
|
86
86
|
useLayoutEffect(() => {
|
|
87
87
|
update()
|
|
88
88
|
|
|
89
89
|
const observer = new MutationObserver((mutations) => {
|
|
90
|
-
const
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
return true
|
|
95
|
-
}
|
|
96
|
-
// Only check added nodes when anchor is a string selector
|
|
97
|
-
if (
|
|
98
|
-
typeof anchor === 'string' &&
|
|
99
|
-
[...addedNodes].some((node) => node instanceof Element && node.matches?.(anchor))
|
|
100
|
-
) {
|
|
101
|
-
return true
|
|
102
|
-
}
|
|
103
|
-
return false
|
|
104
|
-
})
|
|
105
|
-
shouldUpdate && update()
|
|
90
|
+
const isSelfMutation = mutations
|
|
91
|
+
.flatMap(({ addedNodes, removedNodes }) => [...addedNodes, ...removedNodes])
|
|
92
|
+
.some((node) => container?.contains(node))
|
|
93
|
+
!isSelfMutation && update()
|
|
106
94
|
})
|
|
107
95
|
|
|
108
96
|
observer.observe(document.body, {
|
|
109
97
|
childList: true,
|
|
110
98
|
subtree: true
|
|
111
99
|
})
|
|
112
|
-
|
|
113
100
|
return () => observer.disconnect()
|
|
114
|
-
}, [update, anchor])
|
|
101
|
+
}, [update, anchor, container])
|
|
115
102
|
|
|
116
103
|
useEffect(() => {
|
|
117
104
|
if (container && anchorRef.current) {
|