@neuphlo/widget-react 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @neuphlo/widget-react
+
+React bindings for the [Neuphlo](https://neuphlo.com) support chat widget. Renders a floating launcher; conversations land in your Neuphlo inbox with the same draft-and-approve flow as email.
+
+## Install
+
+```bash
+npm install @neuphlo/widget-react
+```
+
+## Usage
+
+Mount the component anywhere in your tree (it renders nothing):
+
+```tsx
+import { NeuphloWidget } from "@neuphlo/widget-react"
+
+export function App() {
+  return (
+    <>
+      <YourApp />
+      <NeuphloWidget widgetKey="your-widget-key" />
+    </>
+  )
+}
+```
+
+Or use the hook:
+
+```tsx
+import { useNeuphloWidget } from "@neuphlo/widget-react"
+
+useNeuphloWidget({ widgetKey: "your-widget-key", position: "left", color: "#0f766e" })
+```
+
+Open the panel programmatically (e.g. from a "Contact support" button):
+
+```tsx
+import { openNeuphloWidget } from "@neuphlo/widget-react"
+
+<button onClick={openNeuphloWidget}>Contact support</button>
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `widgetKey` | — | Workspace widget key from Inbox settings → Chat widget |
+| `position` | `"right"` | Launcher corner, `"left"` or `"right"` |
+| `color` | `"#171717"` | Launcher accent color |
+| `appUrl` | Neuphlo cloud | Your app origin for self-hosted installs |
+| `scriptUrl` | `https://get.neuphlo.com/widget.js` | Loader script URL |
+
+The widget unmounts cleanly — the launcher and panel are removed when the component unmounts.

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+declare global {
+    interface Window {
+        __neuphloWidgetLoaded?: boolean;
+        NeuphloWidget?: NeuphloWidgetApi;
+    }
+}
+export interface NeuphloWidgetApi {
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    destroy: () => void;
+}
+export interface NeuphloWidgetOptions {
+    /** Workspace widget key from Inbox settings → Chat widget. */
+    widgetKey: string;
+    /** Loader script origin. Defaults to the Neuphlo cloud. */
+    scriptUrl?: string;
+    /** Neuphlo app origin, for self-hosted installs. */
+    appUrl?: string;
+    /** Launcher corner. Defaults to "right". */
+    position?: "left" | "right";
+    /** Launcher accent color, any CSS color. */
+    color?: string;
+}
+export declare function loadNeuphloWidget(options: NeuphloWidgetOptions): () => void;
+export declare function useNeuphloWidget(options: NeuphloWidgetOptions): void;
+export declare function NeuphloWidget(props: NeuphloWidgetOptions): null;
+export declare function openNeuphloWidget(): void;
+export declare function closeNeuphloWidget(): void;

package/dist/index.js

@@ -0,0 +1,41 @@
+import { useEffect } from "react";
+const DEFAULT_SCRIPT_URL = "https://get.neuphlo.com/widget.js";
+const SCRIPT_ID = "neuphlo-widget-loader";
+export function loadNeuphloWidget(options) {
+    if (typeof document === "undefined")
+        return () => { };
+    if (document.getElementById(SCRIPT_ID) || window.__neuphloWidgetLoaded) {
+        return () => { };
+    }
+    const script = document.createElement("script");
+    script.id = SCRIPT_ID;
+    script.src = options.scriptUrl ?? DEFAULT_SCRIPT_URL;
+    script.async = true;
+    script.dataset.key = options.widgetKey;
+    if (options.appUrl)
+        script.dataset.app = options.appUrl;
+    if (options.position)
+        script.dataset.position = options.position;
+    if (options.color)
+        script.dataset.color = options.color;
+    document.body.appendChild(script);
+    return () => {
+        window.NeuphloWidget?.destroy();
+        script.remove();
+        window.__neuphloWidgetLoaded = false;
+    };
+}
+export function useNeuphloWidget(options) {
+    const { widgetKey, scriptUrl, appUrl, position, color } = options;
+    useEffect(() => loadNeuphloWidget({ widgetKey, scriptUrl, appUrl, position, color }), [widgetKey, scriptUrl, appUrl, position, color]);
+}
+export function NeuphloWidget(props) {
+    useNeuphloWidget(props);
+    return null;
+}
+export function openNeuphloWidget() {
+    window.NeuphloWidget?.open();
+}
+export function closeNeuphloWidget() {
+    window.NeuphloWidget?.close();
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@neuphlo/widget-react",
+  "version": "0.1.0",
+  "description": "React component for the Neuphlo support chat widget",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Neuphlo/neuphlo-widget-react.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^5.9.0"
+  },
+  "bugs": "https://github.com/Neuphlo/neuphlo-widget-react/issues",
+  "homepage": "https://github.com/Neuphlo/neuphlo-widget-react#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}