@enquio/react-popup 1.0.2 → 1.2.0

package/README.md

@@ -1,96 +1,74 @@
-# @enquio/react
+# @enquio/react-popup
 
-React wrapper component for the Enquio popup Web Component. Provides a React-idiomatic interface to integrate Enquio popups into your React applications.
+See the [installation prerequisites](../../docs/installation.md), [support matrix](../../docs/support-matrix.md) and [troubleshooting](../../docs/troubleshooting.md). Registry commands assume a matching published release; local verification uses tarballs and does not establish npm/CDN availability.
 
-## 📦 Installation
+React wrapper for the Enquio popup Web Component.
 
-```bash
-npm install @enquio/react
+```sh
+npm install @enquio/react-popup
 ```
 
-## ✅ Requirements
+<!-- example:react -->
 
-- **React**: >=17
-- **React-DOM**: >=17
-
-## 🚀 Quick Start
-
-### Basic Usage
-
-```typescript
-import { EnquioPopup } from '@enquio/react';
+```tsx
+import { EnquioPopup } from '@enquio/react-popup';
 
 export default function App() {
-  return (
-    <div>
-      <h1>My App</h1>
-      <EnquioPopup projectId="your-project-id" />
-    </div>
-  );
+	return <EnquioPopup projectId="YOUR_PROJECT_ID" />;
 }
 ```
 
-## 📖 API
+`projectId` is a required string. Updating it updates the custom element's `project-id` attribute. The wrapper loads the shared runtime on mount; StrictMode and remount share the loader's initialization. Failures are caught without error UI, with diagnostics provided by the [core loader](../core/README.md). After a transport failure, a later mount can retry.
 
-### `EnquioPopup`
+For consent, mount the component only after the host grants permission and unmount it on revocation. Place it outside transformed/clipped ancestors. Use one installation method per document; see the [compatibility contract](../../../EnquioClient/docs/integrations/embed-compatibility.md).
 
-A React component that renders the Enquio popup Web Component.
+## Distribution and types
 
-#### Props
+Both ESM and CommonJS entrypoints include TypeScript declarations:
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `projectId` | `string` | Yes | Your Enquio project ID |
-
-#### Example
-
-```typescript
-<EnquioPopup projectId="abc-123-def-456" />
+```js
+import { EnquioPopup } from '@enquio/react-popup';
 ```
 
-## 🔧 Advanced Usage
+```js
+const { EnquioPopup } = require('@enquio/react-popup');
+```
 
-### Using Refs
+React and React DOM are peer dependencies; the shared `@enquio/popup-core` loader is a dependency. The component does not install a global JSX declaration for the raw custom element or expose a ref prop.
 
-You can access the underlying DOM element using React refs:
+## Verified compatibility
 
-```typescript
-import { useRef, useEffect } from 'react';
-import { EnquioPopup } from '@enquio/react';
+Peer range: React and React DOM `>=17.0.0 <20`, using matching runtime versions.
 
-export default function App() {
-  const popupRef = useRef<HTMLElement>(null);
+Locally verified on 2026-09-25 with Node 24.21.0, TypeScript 5.9.3 and Chromium, Firefox and WebKit through Playwright 1.62.1:
 
-  useEffect(() => {
-    // Access custom element directly if needed
-    if (popupRef.current) {
-      console.log('Popup ready:', popupRef.current);
-    }
-  }, []);
+| React / React DOM | @types/react | @types/react-dom |
+| ----------------- | ------------ | ---------------- |
+| 17.0.0            | 17.0.89      | 17.0.26          |
+| 18.0.0            | 18.3.28      | 18.3.7           |
+| 19.0.0            | 19.3.0       | 19.3.0           |
+| 19.3.0            | 19.3.0       | 19.3.0           |
 
-  return <enquio-popup ref={popupRef} project-id="your-project-id" />;
-}
-```
+This covers representative versions and each major's lower runtime boundary, not every version in the peer range.
 
-### With TypeScript
+From the workspace root:
 
-The component is fully typed:
+```sh
+npm ci
+npx playwright install chromium firefox webkit
+npm run test:react-package
+```
 
-```typescript
-import { EnquioPopup } from '@enquio/react';
-import type { ReactElement } from 'react';
+The command builds and packs core and React, installs the tarballs into clean temporary consumers outside the workspace, and tests:
 
-export default function App(): ReactElement {
-  return <EnquioPopup projectId="your-project-id" />;
-}
-```
+- All declared entrypoints, native ESM import and CommonJS require without browser globals.
+- TypeScript Node16, NodeNext and Bundler resolution with `skipLibCheck: false`, JSX usage, and invalid/missing `projectId` rejection.
+- Development StrictMode, project changes, unmount/remount before and after readiness, delayed registration, and transport failure/retry without duplicate runtime initialization or unhandled errors.
 
-## 🔗 Dependencies
+The runner needs npm registry access and the three installed Playwright engines. It removes its temporary consumers on success and retains them for inspection on failure. Browser tests use a simulated remote runtime with the real packaged loader; they do not verify a published npm release, live CDN or Next.js SSR/hydration. See the [Next.js example and Docker tests](../../docs/ssr-examples.md).
 
-- `@enquio/core`: Core script loader
-- `react`: Peer dependency (must be installed separately)
-- `react-dom`: Peer dependency (must be installed separately)
+MIT Copyright Enquio Team
 
-## 📝 License
+## SSR framework example
 
-MIT © Enquio Team
+The ESM and CommonJS package entries preserve `"use client"`. Import the package directly from a Next App Router server layout. See the [runnable examples](../../docs/ssr-examples.md) and [support matrix](../../docs/support-matrix.md) for exact scope.

package/dist/{index.js → index.cjs}

@@ -1,4 +1,6 @@
+"use client";
 "use strict";
+"use client";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -27,12 +29,12 @@ module.exports = __toCommonJS(index_exports);
 // src/EnquioPopup.tsx
 var import_react = require("react");
 var import_popup_core = require("@enquio/popup-core");
-var import_jsx_runtime = require("react/jsx-runtime");
 function EnquioPopup({ projectId }) {
   (0, import_react.useEffect)(() => {
-    (0, import_popup_core.loadEnquioScript)().then(() => customElements.whenDefined("enquio-popup")).catch(console.error);
+    void (0, import_popup_core.loadEnquioScript)().catch(() => {
+    });
   }, []);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("enquio-popup", { "project-id": projectId });
+  return (0, import_react.createElement)("enquio-popup", { "project-id": projectId });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -1,12 +1,15 @@
+"use client";
+"use client";
+
 // src/EnquioPopup.tsx
-import { useEffect } from "react";
+import { createElement, useEffect } from "react";
 import { loadEnquioScript } from "@enquio/popup-core";
-import { jsx } from "react/jsx-runtime";
 function EnquioPopup({ projectId }) {
   useEffect(() => {
-    loadEnquioScript().then(() => customElements.whenDefined("enquio-popup")).catch(console.error);
+    void loadEnquioScript().catch(() => {
+    });
   }, []);
-  return /* @__PURE__ */ jsx("enquio-popup", { "project-id": projectId });
+  return createElement("enquio-popup", { "project-id": projectId });
 }
 export {
   EnquioPopup

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@enquio/react-popup",
-	"version": "1.0.2",
+	"version": "1.2.0",
 	"description": "React popup component for Enquio Web Component",
 	"main": "dist/index.cjs",
 	"module": "dist/index.mjs",
@@ -28,8 +28,8 @@
 	"license": "MIT",
 	"author": "Enquio Team",
 	"peerDependencies": {
-		"react": ">=17",
-		"react-dom": ">=17"
+		"react": ">=17.0.0 <20",
+		"react-dom": ">=17.0.0 <20"
 	},
 	"devDependencies": {
 		"@types/react": "^18.2.0",
@@ -38,11 +38,23 @@
 		"typescript": "^5.3.0"
 	},
 	"dependencies": {
-		"@enquio/popup-core": "1.0.2"
+		"@enquio/popup-core": "1.2.0"
 	},
 	"scripts": {
 		"build": "tsup",
 		"clean": "rm -rf dist",
 		"prepublishOnly": "npm run build"
+	},
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.cjs"
+			}
+		}
 	}
 }