react-magic-portal 1.1.0

package/.commitlintrc

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "@commitlint/config-conventional"
+  ]
+}

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# https://github.com/dependabot/dependabot-core/issues/1736
+
+version: 2
+updates:
+  # Enable version updates for npm
+  - package-ecosystem: 'npm'
+    # Look for `package.json` and `lock` files in the `root` directory
+    directory: '/'
+    # Check the npm registry for updates every day (weekdays)
+    schedule:
+      interval: 'weekly'

package/.github/workflows/cd.yml

@@ -0,0 +1,85 @@
+name: CD
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      cache-hit: ${{ steps.pnpm-cache.outputs.cache-hit }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - name: Cache pnpm store
+        uses: actions/cache@v3
+        id: pnpm-cache
+        with:
+          path: |
+            ~/.pnpm-store
+            node_modules
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+  linter:
+    needs: [setup]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - name: Restore dependencies
+        if: needs.setup.outputs.cache-hit != 'true'
+        run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: pnpm run lint
+      - run: pnpm run check
+
+  tests:
+    needs: [setup]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - name: Restore dependencies
+        if: needs.setup.outputs.cache-hit != 'true'
+        run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: pnpm run test
+  release:
+    needs: [setup, linter, tests]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - name: Restore dependencies
+        if: needs.setup.outputs.cache-hit != 'true'
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - run: pnpm run build
+      - run: pnpm semantic-release
+        env:
+          GH_TOKEN: ${{ secrets.REACT_DYNAMIC_PORTAL_GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.REACT_DYNAMIC_PORTAL_NPM_TOKEN }}

package/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      cache-hit: ${{ steps.pnpm-cache.outputs.cache-hit }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - name: Cache pnpm store
+        uses: actions/cache@v3
+        id: pnpm-cache
+        with:
+          path: |
+            ~/.pnpm-store
+            node_modules
+          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-
+  linter:
+    needs: [setup]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - name: Restore dependencies
+        if: needs.setup.outputs.cache-hit != 'true'
+        run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: pnpm run lint
+      - run: pnpm run check
+
+  tests:
+    needs: [setup]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - name: Restore dependencies
+        if: needs.setup.outputs.cache-hit != 'true'
+        run: pnpm install --frozen-lockfile
+      - run: pnpm run build
+      - run: pnpm run test

package/.husky/commit-msg

@@ -0,0 +1 @@
+pnpm commitlint --edit "$1"

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm lint && pnpm check

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "none",
+  "printWidth": 120
+}

package/.releaserc

@@ -0,0 +1,13 @@
+{
+  "branches": [
+    "master"
+  ],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/github",
+    "@semantic-release/npm",
+    "@semantic-release/git"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# [1.1.0](https://github.com/molvqingtai/react-magic-portal/compare/v1.0.0...v1.1.0) (2025-09-24)
+
+
+### Features
+
+* rename repo ([794af06](https://github.com/molvqingtai/react-magic-portal/commit/794af06f683a6c330132fbb2951b3abf39f167df))
+
+# 1.0.0 (2025-09-24)
+
+
+### Features
+
+* release v1.0.0 ([a79203b](https://github.com/molvqingtai/react-dynamic-portal/commit/a79203b02295e0cb40404ce7a208667410b42054))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John Wu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# React Magic Portal
+
+A React component designed for browser extension development that provides magical portal functionality with automatic anchor detection and DOM mutation monitoring.
+
+[![version](https://img.shields.io/github/v/release/molvqingtai/react-magic-portal)](https://www.npmjs.com/package/react-magic-portal) [![workflow](https://github.com/molvqingtai/react-magic-portal/actions/workflows/ci.yml/badge.svg)](https://github.com/molvqingtai/react-magic-portal/actions) [![download](https://img.shields.io/npm/dt/react-magic-portal)](https://www.npmjs.com/package/react-magic-portal) [![npm package minimized gzipped size](https://img.shields.io/bundlejs/size/react-magic-portal)](https://www.npmjs.com/package/react-magic-portal) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/molvqingtai/react-magic-portal)
+
+```bash
+$ pnpm add react-magic-portal
+```
+
+## Introduction
+
+When developing browser extensions with React, you often need to inject React components into host web pages. However, the target mounting points in these pages are frequently dynamic - they may not exist when your extension loads, or they might be created and destroyed as users navigate and interact with the page.
+
+Traditional React portals require the target DOM element to exist before rendering, which creates challenges in browser extension scenarios where:
+
+- **Host pages load content dynamically** - Target elements appear after AJAX requests, user interactions, or page navigation
+- **Single Page Applications (SPAs)** - Content changes without full page reloads, causing mounting points to appear and disappear
+- **Dynamic DOM manipulation** - Third-party scripts or frameworks modify the DOM structure continuously
+- **Uncertain timing** - You can't predict when or if target elements will be available
+
+React Magic Portal solves these challenges by automatically detecting when target elements appear or disappear in the DOM, ensuring your React components are always rendered in the right place at the right time.
+
+## Features
+
+- **Magic Anchor Detection** - Automatically detects when target elements appear or disappear in the DOM
+- **Multiple Positioning Options** - Support for `append`, `prepend`, `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
+
+## Usage
+
+### Magic Content Loading
+
+```jsx
+function MagicContent() {
+  const [showTarget, setShowTarget] = useState(false)
+
+  return (
+    <div>
+      <button onClick={() => setShowTarget(!showTarget)}>Toggle Target</button>
+
+      {showTarget && <div id="anchor-target">Magic Target Element</div>}
+
+      {/* Portal will automatically mount/unmount based on target availability */}
+      <MagicPortal
+        anchor="#anchor-target"
+        onMount={() => console.log('Portal mounted')}
+        onUnmount={() => console.log('Portal unmounted')}
+      >
+        <div>This content follows the target element</div>
+      </MagicPortal>
+    </div>
+  )
+}
+```
+
+### Multiple Portals on Same Anchor
+
+```jsx
+function MultiplePortals() {
+  return (
+    <div>
+      <div id="target">Target Element</div>
+
+      <MagicPortal anchor="#target" position="before">
+        <div>Content before target</div>
+      </MagicPortal>
+
+      <MagicPortal anchor="#target" position="prepend">
+        <div>Content at start of target</div>
+      </MagicPortal>
+
+      <MagicPortal anchor="#target" position="append">
+        <div>Content at end of target</div>
+      </MagicPortal>
+
+      <MagicPortal anchor="#target" position="after">
+        <div>Content after target</div>
+      </MagicPortal>
+    </div>
+  )
+}
+```
+
+## API Reference
+
+### 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.ReactNode`                                                                          | **Required** | The content to render in the portal                          |
+| `onMount`   | `(anchor: Element, container: HTMLDivElement) => void`                                     | `undefined`  | Callback fired when the portal is mounted                    |
+| `onUnmount` | `(anchor: Element, container: HTMLDivElement) => void`                                     | `undefined`  | Callback fired when the portal is unmounted                  |
+| `ref`       | `React.Ref<HTMLDivElement \| null>`                                                        | `undefined`  | Ref to the portal container element                          |
+| `key`       | `React.Key`                                                                                | `undefined`  | Key for the ReactDOM.createPortal                            |
+
+### Anchor Types
+
+#### CSS Selector String
+
+```jsx
+<MagicPortal anchor="#my-element">
+  <div>Content</div>
+</MagicPortal>
+
+<MagicPortal anchor=".my-class">
+  <div>Content</div>
+</MagicPortal>
+```
+
+#### Element Reference
+
+```jsx
+const elementRef = useRef(null)
+
+<div ref={elementRef}>Target</div>
+<MagicPortal anchor={elementRef}>
+  <div>Content</div>
+</MagicPortal>
+```
+
+#### Function
+
+```jsx
+<MagicPortal anchor={() => document.querySelector('.magic-element')}>
+  <div>Content</div>
+</MagicPortal>
+```
+
+#### Direct Element
+
+```jsx
+<MagicPortal anchor={document.body}>
+  <div>Content</div>
+</MagicPortal>
+```
+
+### Position Options
+
+#### `append` (default)
+
+Adds content inside the anchor element at the end:
+
+```html
+<div id="anchor">
+  Existing content
+  <!-- Portal content appears here -->
+</div>
+```
+
+#### `prepend`
+
+Adds content inside the anchor element at the beginning:
+
+```html
+<div id="anchor">
+  <!-- Portal content appears here -->
+  Existing content
+</div>
+```
+
+#### `before`
+
+Adds content as a sibling before the anchor element:
+
+```html
+<!-- Portal content appears here -->
+<div id="anchor">Existing content</div>
+```
+
+#### `after`
+
+Adds content as a sibling after the anchor element:
+
+```html
+<div id="anchor">Existing content</div>
+<!-- Portal content appears here -->
+```
+
+## License
+
+MIT © [molvqingtai](https://github.com/molvqingtai)

package/__tests__/eslint.config.ts

@@ -0,0 +1,25 @@
+import globals from 'globals'
+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'
+
+export default defineConfig([
+  { files: ['**/*.{js,mjs,cjs,ts}'] },
+  {
+    languageOptions: {
+      globals: { ...globals.browser, ...globals.node },
+      parserOptions: { project: './tsconfig.json', tsconfigRootDir: import.meta.dirname }
+    }
+  },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+  prettierPlugin,
+  reactHooks.configs['recommended-latest'],
+  reactRefresh.configs.vite,
+  {
+    ignores: ['**/dist/*']
+  }
+])

package/__tests__/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "__tests__",
+  "version": "0.0.0",
+  "description": "Test suite for react-dynamic-portal",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint --fix --cache",
+    "check": "tsc --noEmit"
+  },
+  "keywords": [],
+  "author": "molvqingtai",
+  "license": "MIT",
+  "dependencies": {
+    "react-magic-portal": "workspace:*"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
+    "@vitejs/plugin-react": "^5.0.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.36.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.21",
+    "globals": "^16.4.0",
+    "happy-dom": "^18.0.1",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.44.1",
+    "vite": "^7.1.7",
+    "vitest": "^3.2.4"
+  }
+}