@cas0570/chat-widget 0.0.1

package/README.md

@@ -0,0 +1,367 @@
+# GeoApps Chat Widget
+
+> Embeddable React chat widget for GeoApps documentation assistant.
+
+---
+
+## Overview
+
+| | |
+| --- | --- |
+| **Type** | Frontend Component Library |
+| **Framework** | React 18 + TypeScript |
+| **Purpose** | Embed chat functionality in any website |
+| **Bundle Formats** | ESM, UMD, IIFE |
+
+The Chat Widget provides a floating chat button and dialog that connects to the GeoApps Chat API for RAG-powered documentation assistance.
+
+---
+
+## Quick Start
+
+### NPM Installation
+
+```bash
+npm install @geoapps/chat-widget
+```
+
+### React Usage
+
+```tsx
+import { ChatWidget } from '@geoapps/chat-widget'
+import '@geoapps/chat-widget/style.css'
+
+function App() {
+  return (
+    <ChatWidget
+      apiUrl="https://api.geoapps.nl/api/v1/chat"
+      title="GeoApps Help"
+    />
+  )
+}
+```
+
+---
+
+## Features
+
+| Feature | Description |
+| --------- | ------------- |
+| 💬 **Floating Chat** | Collapsible chat bubble with dialog |
+| 📡 **Streaming** | Real-time response streaming via SSE |
+| 🎨 **Customizable** | Full control over colors, text, positioning |
+| 📱 **Responsive** | Works on desktop and mobile |
+| ♿ **Accessible** | WCAG compliant with keyboard navigation |
+| 🌐 **Framework Agnostic** | Works with any frontend via script tag |
+
+---
+
+## Installation Methods
+
+### Method 1: NPM Package
+
+```bash
+npm install @geoapps/chat-widget
+# or
+yarn add @geoapps/chat-widget
+# or
+pnpm add @geoapps/chat-widget
+```
+
+---
+
+## Usage
+
+### React Component
+
+```tsx
+import { ChatWidget } from '@geoapps/chat-widget'
+import '@geoapps/chat-widget/style.css'
+
+function App() {
+  return (
+    <ChatWidget
+      apiUrl="https://api.geoapps.nl/api/v1/chat"
+      title="GeoApps Help"
+      subtitle="Vraag me iets over GeoApps"
+      primaryColor="#3b82f6"
+      position="bottom-right"
+      placeholder="Typ je vraag..."
+    />
+  )
+}
+```
+
+### Vue.js
+
+```vue
+<template>
+  <ChatWidget
+    api-url="https://api.geoapps.nl/api/v1/chat"
+    title="GeoApps Help"
+  />
+</template>
+
+<script setup>
+import { ChatWidget } from '@geoapps/chat-widget'
+import '@geoapps/chat-widget/style.css'
+</script>
+```
+
+### Next.js
+
+```tsx
+'use client'
+
+import dynamic from 'next/dynamic'
+import '@geoapps/chat-widget/style.css'
+
+const ChatWidget = dynamic(
+  () => import('@geoapps/chat-widget').then(mod => mod.ChatWidget),
+  { ssr: false }
+)
+
+export default function Page() {
+  return <ChatWidget apiUrl="https://api.geoapps.nl/api/v1/chat" />
+}
+```
+
+---
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| ------ | ------ | --------- | ------------- |
+| `apiUrl` | `string` | **Required** | Chat API endpoint URL |
+| `tenantId` | `string` | `""` | Optional tenant ID for multi-tenant setup |
+| `title` | `string` | `"Chat"` | Dialog header title |
+| `subtitle` | `string` | `""` | Dialog header subtitle |
+| `placeholder` | `string` | `"Typ een bericht..."` | Input placeholder text |
+| `greeting` | `string` | `""` | Initial greeting message |
+| `primaryColor` | `string` | `"#3b82f6"` | Main accent color (hex) or var() |
+| `position` | `Position` | `"bottom-right"` | Widget position |
+| `defaultOpen` | `boolean` | `false` | Default open state |
+| `defaultSize` | `WidgetSize` | `medium` | Default widget size |
+| `headers` | `Record<string, string>` | `""` | Custom headers for API calls |
+
+### Position Options
+
+```typescript
+'bottom-right' 
+'bottom-left' 
+'top-right' 
+'top-left'
+```
+
+### Widget Sizes
+
+```typescript
+'small'
+'medium'
+'large'
+'fullscreen'
+```
+
+### Events / Callbacks
+
+| Prop | Type | Description |
+| ------ | ------ | ------------- |
+| `onOpen` | `() => void` | Called when chat dialog opens |
+| `onClose` | `() => void` | Called when chat dialog closes |
+| `onMessageSent` | `(message: string) => void` | Called when message is sent |
+| `onResponseReceived` | `(response: string) => void` | Called when a response is received |
+
+### Example with Callbacks
+
+```tsx
+<ChatWidget
+  apiUrl="https://api.geoapps.nl/api/v1/chat"
+  onOpen={() => analytics.track('chat_opened')}
+  onClose={() => analytics.track('chat_closed')}
+  onMessageSent={(msg) => console.log('Message:', msg)}
+/>
+```
+
+---
+
+## Customization
+
+### Theme Customization
+
+```tsx
+<ChatWidget
+  apiUrl="..."
+  primaryColor="#10b981"      // Green theme
+  // CSS variables available:
+  // --chat-primary: primaryColor
+  // --chat-primary-hover: auto-generated
+  // --chat-bg: white
+  // --chat-text: #1f2937
+/>
+```
+
+### Custom CSS
+
+```css
+/* Override default styles */
+.geoapps-chat-widget {
+  --chat-font-family: 'Inter', sans-serif;
+  --chat-border-radius: 16px;
+}
+
+.geoapps-chat-bubble {
+  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
+}
+
+.geoapps-chat-message--bot {
+  background: #f3f4f6;
+}
+```
+
+### Custom Chat Bubble
+
+```tsx
+import { ChatWidget, ChatBubble } from '@geoapps/chat-widget'
+
+// Use custom trigger button
+<ChatWidget
+  apiUrl="..."
+  renderTrigger={({ isOpen, toggle }) => (
+    <button onClick={toggle}>
+      {isOpen ? 'Close Chat' : 'Need Help?'}
+    </button>
+  )}
+/>
+```
+
+---
+
+## Project Structure
+
+```txt
+geoapps-chat-widget/
+├── src/
+│   ├── index.ts              # Package exports
+│   ├── embed.ts              # IIFE entry for script tag
+│   ├── components/
+│   │   ├── ChatWidget.tsx    # Main widget component
+│   │   ├── ChatBubble.tsx    # Floating button
+│   │   ├── ChatDialog.tsx    # Chat dialog window
+│   │   ├── ChatMessage.tsx   # Message bubble
+│   │   ├── ChatInput.tsx     # Text input
+│   │   └── SourceLink.tsx    # Source reference
+│   ├── hooks/
+│   │   ├── useChat.ts        # Chat logic hook
+│   │   ├── useStream.ts      # SSE streaming hook
+│   │   └── useSession.ts     # Session persistence
+│   ├── styles/
+│   │   ├── widget.css        # Main styles
+│   │   └── variables.css     # CSS variables
+│   └── types/
+│       └── index.ts          # TypeScript types
+├── dist/                     # Built files
+│   ├── index.js              # ESM bundle
+│   ├── index.cjs             # CommonJS bundle
+│   ├── embed.iife.js         # Script tag bundle
+│   └── style.css             # Styles
+├── package.json
+├── tsconfig.json
+├── vite.config.ts            # Build configuration
+└── README.md
+```
+
+---
+
+## Development
+
+### Local Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build library
+npm run build:lib
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Type check
+npm run type-check
+```
+
+### Testing Locally
+
+```bash
+# Start dev server with demo page
+npm run dev
+
+# Open http://localhost:5173/demo.html
+```
+
+### Publishing
+
+```bash
+# Build production bundle
+npm run build:lib
+
+# Publish to npm
+npm publish --access public
+```
+
+---
+
+## Browser Support
+
+| Browser | Version |
+| --------- | --------- |
+| Chrome | 80+ |
+| Firefox | 75+ |
+| Safari | 14+ |
+| Edge | 80+ |
+| Mobile Safari | 14+ |
+| Chrome Android | 80+ |
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+| ------- | ---------- |
+| Widget not appearing | Check z-index conflicts |
+| CORS errors | Ensure API allows your domain in CORS_ORIGINS |
+| Messages not sending | Verify apiUrl is correct and API is running |
+| Styles not loading | Import the CSS file: `import '@geoapps/chat-widget/style.css'` |
+| SSR errors (Next.js) | Use dynamic import with `ssr: false` |
+
+---
+
+## Accessibility
+
+The widget follows WCAG 2.1 guidelines:
+
+- ✅ Keyboard navigation (Tab, Enter, Escape)
+- ✅ Focus management
+- ✅ ARIA labels
+- ✅ Color contrast ratios
+- ✅ Screen reader support
+
+---
+
+## Related Documentation
+
+- [Main README](https://github.com/geoapps/geoapps-chatbot/) - Repository overview
+- [Chat API](https://github.com/geoapps/geoapps-chat-api/)- Backend service
+- [Doc Indexer](https://github.com/geoapps/geoapps-doc-indexer/) - Index documentation
+
+---
+
+Built with ❤️ by [Cas Doorn](https://casdoorn.nl)

package/dist/components/ChatBubble.d.ts

@@ -0,0 +1,8 @@
+import { Message } from '../types';
+
+interface ChatBubbleProps {
+    message: Message;
+    primaryColor: string;
+}
+export declare function ChatBubble({ message, primaryColor }: ChatBubbleProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ChatWidget.d.ts

@@ -0,0 +1,3 @@
+import { ChatWidgetProps } from '../types';
+
+export declare function ChatWidget({ apiUrl, tenantId, title, subtitle, placeholder, greeting, primaryColor, position, defaultOpen, defaultSize, headers, onOpen, onClose, onMessageSent, onResponseReceived, }: ChatWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/ChatWindow.d.ts

@@ -0,0 +1,18 @@
+import { Message, WidgetSize } from '../types';
+
+interface ChatWindowProps {
+    title: string;
+    subtitle: string;
+    placeholder: string;
+    messages: Message[];
+    isLoading: boolean;
+    onSendMessage: (content: string) => void;
+    onClose: () => void;
+    onClear: () => void;
+    onSizeChange: (size: WidgetSize) => void;
+    onPopout: () => void;
+    primaryColor: string;
+    size: WidgetSize;
+}
+export declare function ChatWindow({ title, subtitle, placeholder, messages, isLoading, onSendMessage, onClose, onClear, onSizeChange, onPopout, primaryColor, size, }: ChatWindowProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Icons.d.ts

@@ -0,0 +1,26 @@
+import { WidgetSize } from '../types';
+
+interface ResizeIconProps {
+    size: WidgetSize;
+    className?: string;
+}
+export declare function ResizeIcon({ size, className }: ResizeIconProps): import("react/jsx-runtime").JSX.Element;
+export declare function ExpandIcon({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ContractIcon({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function PopoutIcon({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function CloseIcon({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function TrashIcon({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function ChatIcon({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/MarkdownRenderer.d.ts

@@ -0,0 +1,6 @@
+interface MarkdownRendererProps {
+    content: string;
+    className?: string;
+}
+export declare function MarkdownRenderer({ content, className }: MarkdownRendererProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/MessageInput.d.ts

@@ -0,0 +1,8 @@
+interface MessageInputProps {
+    placeholder: string;
+    isLoading: boolean;
+    onSendMessage: (content: string) => void;
+    primaryColor: string;
+}
+export declare function MessageInput({ placeholder, isLoading, onSendMessage, primaryColor }: MessageInputProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/MessageList.d.ts

@@ -0,0 +1,9 @@
+import { Message } from '../types';
+
+interface MessageListProps {
+    messages: Message[];
+    isLoading: boolean;
+    primaryColor: string;
+}
+export declare function MessageList({ messages, isLoading, primaryColor }: MessageListProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/PopoutWindow.d.ts

@@ -0,0 +1,25 @@
+import { Message, WidgetSize } from '../types';
+
+interface PopoutConfig {
+    apiUrl: string;
+    tenantId?: string;
+    title: string;
+    subtitle: string;
+    placeholder: string;
+    primaryColor: string;
+    sessionId?: string | null;
+    messages: Message[];
+    headers?: Record<string, string>;
+}
+interface UsePopoutReturn {
+    isPoppedOut: boolean;
+    openPopout: () => void;
+    closePopout: () => void;
+    focusPopout: () => void;
+}
+/**
+ * Hook to manage the popout window state
+ */
+export declare function usePopout(config: PopoutConfig, size: WidgetSize, onPopoutClose?: () => void): UsePopoutReturn;
+export declare function ChatWindowStandalone(): null;
+export {};

package/dist/components/ToggleButton.d.ts

@@ -0,0 +1,9 @@
+interface ToggleButtonProps {
+    isOpen: boolean;
+    onClick: () => void;
+    primaryColor: string;
+    hasUnread?: boolean;
+    isPoppedOut?: boolean;
+}
+export declare function ToggleButton({ isOpen, onClick, primaryColor, hasUnread, isPoppedOut }: ToggleButtonProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/TypingIndicator.d.ts

@@ -0,0 +1 @@
+export declare function TypingIndicator(): import("react/jsx-runtime").JSX.Element;

package/dist/components/__tests__/ChatBubble.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/ChatWidget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/ChatWindow.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/Icons.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/MarkdownRenderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/MessageInput.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/MessageList.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/PopoutWindow.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/ToggleButton.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/TypingIndicator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/__tests__/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/index.d.ts

@@ -0,0 +1,9 @@
+export { ChatWidget } from './ChatWidget';
+export { ChatWindow } from './ChatWindow';
+export { ChatBubble } from './ChatBubble';
+export { MessageList } from './MessageList';
+export { MessageInput } from './MessageInput';
+export { ToggleButton } from './ToggleButton';
+export { MarkdownRenderer } from './MarkdownRenderer';
+export { usePopout } from './PopoutWindow';
+export { ResizeIcon, ExpandIcon, ContractIcon, PopoutIcon, CloseIcon, TrashIcon, ChatIcon } from './Icons';

package/dist/embed.d.ts

@@ -0,0 +1,17 @@
+import { ChatWidgetProps } from './types';
+
+/**
+ * Embed the GeoApps Chat Widget into a page
+ *
+ * @example
+ * // Using as a script tag:
+ * <script src="https://cdn.example.com/geoapps-chat-widget.js"></script>
+ * <script>
+ *   GeoAppsChatWidget.embed({
+ *     apiUrl: 'https://api.geoapps.nl/chat',
+ *     title: 'GeoApps Help',
+ *     greeting: 'Hello! How can I help you with GeoApps today?'
+ *   });
+ * </script>
+ */
+export declare function embedChatWidget(props: ChatWidgetProps, containerId?: string): () => void;