@monology-io/chat-widget 1.0.2

package/README.md

@@ -0,0 +1,241 @@
+# @monology-io/chat-widget
+
+[![npm version](https://img.shields.io/npm/v/@monology-io/chat-widget.svg)](https://www.npmjs.com/package/@monology-io/chat-widget)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official React/Next.js package for embedding the [Monology](https://monology.io) chat widget into your application. Build intelligent, conversational experiences with ease.
+
+## 🚀 Features
+
+- ✅ **React & Next.js Support** - Works seamlessly with both React and Next.js applications
+- ✅ **TypeScript Ready** - Full TypeScript support with type definitions included
+- ✅ **User Identity Tracking** - Pass authenticated user data for personalized experiences
+- ✅ **Customizable** - Control widget behavior, appearance, and interactions
+- ✅ **Lightweight** - Optimized bundle size with minimal dependencies
+- ✅ **SSR Compatible** - Works with Next.js App Router and Pages Router
+
+## 📦 Installation
+
+```bash
+npm install @monology-io/chat-widget
+```
+
+Or using yarn:
+
+```bash
+yarn add @monology-io/chat-widget
+```
+
+Or using pnpm:
+
+```bash
+pnpm add @monology-io/chat-widget
+```
+
+## 🎯 Quick Start
+
+### Basic React Usage
+
+```jsx
+import { RenderWidget } from "@monology-io/chat-widget";
+
+export default function App() {
+  return (
+    <div className="App">
+      <RenderWidget urlId="your-widget-url-id" identity={null} />
+    </div>
+  );
+}
+```
+
+### Next.js App Router (Recommended)
+
+For Next.js 13+ with App Router, use dynamic import with SSR disabled:
+
+```jsx
+"use client";
+import dynamic from "next/dynamic";
+
+const RenderWidget = dynamic(
+  () => import("@monology-io/chat-widget").then((mod) => mod.RenderWidget),
+  { ssr: false },
+);
+
+export default function App() {
+  return (
+    <div className="App">
+      <RenderWidget urlId="your-widget-url-id" identity={null} />
+    </div>
+  );
+}
+```
+
+### Next.js Pages Router
+
+```jsx
+import { RenderWidget } from "@monology-io/chat-widget";
+
+export default function Home() {
+  return (
+    <div>
+      <h1>My App</h1>
+      <RenderWidget urlId="your-widget-url-id" identity={null} />
+    </div>
+  );
+}
+```
+
+## 📖 Usage Examples
+
+### With User Identity
+
+Pass authenticated user information for personalized conversations and tracking:
+
+```jsx
+import { RenderWidget } from "@monology-io/chat-widget";
+
+export default function App() {
+  return (
+    <div className="App">
+      <RenderWidget
+        urlId="your-widget-url-id"
+        identity={{
+          id: "user-123",
+          firstName: "John",
+          lastName: "Doe",
+          email: "john.doe@example.com",
+          phone: "1234567890",
+          company: {
+            id: "company-456",
+            name: "Acme Inc",
+          },
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Manual Control (Custom Trigger Button)
+
+Control when the widget opens and closes with your own UI:
+
+```jsx
+import { RenderWidget } from "@monology-io/chat-widget";
+import { useState } from "react";
+
+export default function App() {
+  const [isWidgetOpen, setIsWidgetOpen] = useState(false);
+
+  return (
+    <div className="App">
+      <button onClick={() => setIsWidgetOpen(true)}>Open Chat Support</button>
+
+      {isWidgetOpen && (
+        <RenderWidget
+          urlId="your-widget-url-id"
+          onClose={() => setIsWidgetOpen(false)}
+          hideLauncherButton={true}
+          identity={null}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+### TypeScript Example
+
+```tsx
+import { RenderWidget } from "@monology-io/chat-widget";
+import type { Identity } from "@monology-io/chat-widget";
+
+interface Props {
+  user: Identity | null;
+}
+
+export default function ChatWidget({ user }: Props) {
+  return <RenderWidget urlId="your-widget-url-id" identity={user} />;
+}
+```
+
+## 🔧 API Reference
+
+### `<RenderWidget />` Props
+
+| Prop                 | Type               | Required | Default | Description                                    |
+| -------------------- | ------------------ | -------- | ------- | ---------------------------------------------- |
+| `urlId`              | `string`           | ✅ Yes   | -       | Your widget URL ID from the Monology dashboard |
+| `identity`           | `Identity \| null` | ❌ No    | `null`  | User identity object for authenticated users   |
+| `hideLauncherButton` | `boolean`          | ❌ No    | `false` | Hide the default launcher button               |
+| `onClose`            | `() => void`       | ❌ No    | -       | Callback function when widget is closed        |
+
+### `Identity` Object
+
+```typescript
+interface Identity {
+  id: string; // Unique user identifier
+  firstName?: string; // User's first name
+  lastName?: string; // User's last name
+  email?: string; // User's email address
+  phone?: string; // User's phone number
+  company?: {
+    id: string; // Company identifier
+    name: string; // Company name
+  };
+}
+```
+
+## ⚠️ Important CSS Warning
+
+**The host site should NOT have CSS directly applied to semantic HTML elements** like `p`, `a`, `ul`, `li`, `h1-h6`, etc.
+
+### Why?
+
+Global CSS rules on these elements will conflict with the widget's internal styles and disturb its appearance.
+
+### Solution
+
+Use CSS classes or scoped styles instead of element selectors. For example:
+
+- ❌ Bad: `p { margin: 0; }`
+- ✅ Good: `.my-paragraph { margin: 0; }`
+
+## 🌟 Best Practices
+
+1. **Load Asynchronously** - Use dynamic imports in Next.js to avoid blocking initial page load
+2. **Pass User Data When Available** - If users are logged in, pass their identity to enable tracking and skip verification
+3. **Test on Staging First** - Verify the widget works correctly before deploying to production
+4. **Handle Errors Gracefully** - Wrap the widget in error boundaries for production apps
+5. **Optimize Bundle Size** - Use tree-shaking and code splitting to minimize impact
+
+## 📚 Documentation
+
+For complete documentation, visit:
+
+- [Monology Documentation](https://app.monology.io/docs)
+- [Embedding Guide](https://app.monology.io/docs/widgets/embedding)
+- [Widget Configuration](https://app.monology.io/docs/widgets)
+
+## 🔗 Links
+
+- [Website](https://monology.io)
+- [Dashboard](https://app.monology.io)
+- [Documentation](https://app.monology.io/docs)
+- [npm Package](https://www.npmjs.com/package/@monology-io/chat-widget)
+
+## 🆘 Support
+
+Need help? We're here for you:
+
+- 📧 Email: [contact@monology.io](mailto:contact@monology.io)
+- 💬 Chat: [monology.io](https://monology.io) (use our own widget!)
+- 📖 Docs: [app.monology.io/docs](https://app.monology.io/docs)
+
+## 📝 License
+
+MIT © [Monology](https://monology.io)
+
+---
+
+Made with ❤️ by the [Monology](https://monology.io) team