npm - @a.izzuddin/ai-chat - Versions diffs - 0.2.4 → 0.2.7 - Mend

@a.izzuddin/ai-chat 0.2.4 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -1,61 +1,52 @@
-# @a.izzuddin/ai-chat
+# AI Chat Widget
-A **framework-agnostic** AI chat web component built with Lit and TypeScript. Works seamlessly with React, Vue, Svelte, Angular, and vanilla JavaScript.
+A modern, customizable chat widget built with Lit web components. Features a clean UI, responsive design, and extensive theming options.
-[![npm version](https://img.shields.io/npm/v/@a.izzuddin/ai-chat)](https://www.npmjs.com/package/@a.izzuddin/ai-chat)
-[![npm downloads](https://img.shields.io/npm/dm/@a.izzuddin/ai-chat)](https://www.npmjs.com/package/@a.izzuddin/ai-chat)
+## Features
-## ✨ Features
+- 🎨 **Fully Customizable Theme** - Change colors, backgrounds, and styles
+- 📱 **Responsive Design** - Works seamlessly on desktop, tablet, and mobile
+- 🌓 **Dark Mode Support** - Built-in light and dark themes
+- 📦 **Two Display Modes** - Fullscreen or floating widget
+- 🔧 **Easy Integration** - Simple HTML attributes for configuration
+- ⚡ **Built with Lit** - Fast, lightweight web component
+- 🎯 **TypeScript Support** - Full type safety
+- 📝 **List Formatting** - Automatic rendering of bulleted and numbered lists
+- 💡 **Suggested Questions** - Clickable follow-up questions for better UX
+- 🔗 **Related FAQs** - Display related FAQ references
+- 👋 **Customizable Welcome Message** - Set custom greeting with optional subtitle
-- 🌐 **Framework Agnostic** - Works with any framework or no framework
-- 🎨 **Beautiful UI** - Modern chat interface with light/dark mode
-- ⚡ **Lightweight** - Only ~15KB (gzipped)
-- 🔧 **Fully Customizable** - Configure API endpoint, styling, and behavior
-- 📱 **Responsive** - Mobile-friendly design
-- 🎯 **TypeScript** - Full type safety and IntelliSense
-- ♿ **Accessible** - Semantic HTML and ARIA attributes
-- 🎪 **Event-Driven** - Listen to messages, responses, and errors
+## Quick Start
-## 📦 Installation
+### Installation
 ```bash
 npm install @a.izzuddin/ai-chat
-# or
-yarn add @a.izzuddin/ai-chat
-# or
-pnpm add @a.izzuddin/ai-chat
 ```
-## 🚀 Quick Start
-### Vanilla JavaScript / HTML
+### Basic Usage
+**HTML:**
 ```html
-<!DOCTYPE html>
-<html>
-<body>
-  <script type="module">
-    import '@a.izzuddin/ai-chat';
-  </script>
+<script type="module">
+  import '@a.izzuddin/ai-chat';
+</script>
-  <ai-chat
-    api-url="https://your-api.com"
-    session-id="user-123"
-    title="My AI Assistant">
-  </ai-chat>
-</body>
-</html>
+<ai-chat
+  api-url="https://your-api-endpoint.com"
+  session-id="user-123"
+  title="AI Assistant">
+</ai-chat>
 ```
-### React
-```tsx
+**React:**
+```jsx
 import '@a.izzuddin/ai-chat';
 function App() {
   return (
     <ai-chat
-      api-url={process.env.REACT_APP_API_URL}
+      api-url="https://your-api-endpoint.com"
       session-id="user-123"
       title="AI Assistant"
     />
@@ -63,122 +54,118 @@ function App() {
 }
 ```
-### Vue
+**Vue:**
 ```vue
 <template>
   <ai-chat
-    :api-url="apiUrl"
+    api-url="https://your-api-endpoint.com"
     session-id="user-123"
-    title="AI Assistant"
-  />
+    title="AI Assistant">
+  </ai-chat>
 </template>
 <script setup>
 import '@a.izzuddin/ai-chat';
-const apiUrl = import.meta.env.VITE_API_URL;
 </script>
 ```
-### Svelte
+## Configuration
-```svelte
-<script>
-  import '@a.izzuddin/ai-chat';
-  export let apiUrl;
-</script>
+### Display Modes
+#### Fullscreen Mode (Default)
+```html
 <ai-chat
-  api-url={apiUrl}
+  api-url="https://api.example.com"
   session-id="user-123"
   title="AI Assistant"
-/>
+  mode="fullscreen">
+</ai-chat>
 ```
-### Angular
-```typescript
-import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import '@a.izzuddin/ai-chat';
-@Component({
-  selector: 'app-root',
-  template: '<ai-chat api-url="..." session-id="user-123"></ai-chat>',
-  schemas: [CUSTOM_ELEMENTS_SCHEMA]
-})
-export class AppComponent {}
+#### Widget Mode
+```html
+<ai-chat
+  api-url="https://api.example.com"
+  session-id="user-123"
+  title="AI Assistant"
+  mode="widget"
+  widget-width="400px"
+  widget-height="650px">
+</ai-chat>
 ```
-## 📖 API
+### Theme Customization
-### Attributes
-| Attribute | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `api-url` | `string` | **required** | Your API endpoint URL |
-| `session-id` | `string` | `"default-session"` | Session identifier for conversation context |
-| `title` | `string` | `"My AI Agent"` | Chat header title |
-| `theme` | `"light" \| "dark"` | `"light"` | UI theme |
-| `initial-messages` | `Message[]` | `[]` | Pre-populate chat with messages |
-### Properties (JavaScript)
-```javascript
-const chat = document.querySelector('ai-chat');
-// Set properties
-chat.apiUrl = 'https://api.example.com';
-chat.sessionId = 'user-123';
-chat.title = 'Support Bot';
-chat.theme = 'dark';
-chat.initialMessages = [
-  { id: '1', role: 'assistant', content: 'Hello! How can I help?' }
-];
+#### Custom Colors
+```html
+<ai-chat
+  api-url="https://api.example.com"
+  session-id="user-123"
+  title="AI Assistant"
+  primary-color="#10B981"
+  primary-color-hover="#059669"
+  user-message-bg="#D1FAE5"
+  bot-message-bg="#F3F4F6">
+</ai-chat>
 ```
-### Events
-```javascript
-const chat = document.querySelector('ai-chat');
-// User sends a message
-chat.addEventListener('message-sent', (event) => {
-  console.log('User message:', event.detail);
-  // event.detail: { id: string, role: 'user', content: string }
-});
-// AI responds
-chat.addEventListener('response-received', (event) => {
-  console.log('AI response:', event.detail);
-  // event.detail: { id: string, role: 'assistant', content: string }
-});
-// Error occurs
-chat.addEventListener('error', (event) => {
-  console.error('Chat error:', event.detail);
-  // event.detail: Error object
-});
+#### Custom Avatars and Background
+```html
+<ai-chat
+  api-url="https://api.example.com"
+  session-id="user-123"
+  title="AI Assistant"
+  bot-avatar-url="/path/to/avatar.png"
+  background-image-url="/path/to/background.png">
+</ai-chat>
 ```
-### TypeScript Types
-```typescript
-import type { Message } from '@a.izzuddin/ai-chat';
-interface Message {
-  id: string;
-  role: 'user' | 'assistant';
-  content: string;
-}
+#### Custom Welcome Message
+```html
+<ai-chat
+  api-url="https://api.example.com"
+  session-id="user-123"
+  title="AI Assistant"
+  welcome-message="Hello! How may I assist you?"
+  welcome-subtitle="Ask me anything about our services">
+</ai-chat>
 ```
-## 🔌 Backend API Requirements
+### Dark Mode
+```html
+<ai-chat
+  api-url="https://api.example.com"
+  session-id="user-123"
+  title="AI Assistant"
+  theme="dark">
+</ai-chat>
+```
-Your API must implement this endpoint:
+## Available Attributes
-**POST `/ask`**
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api-url` | string | '' | API endpoint URL for chat backend |
+| `session-id` | string | 'default-session' | Unique session identifier |
+| `title` | string | 'My AI Agent' | Chat widget title |
+| `theme` | 'light' or 'dark' | 'light' | Color theme |
+| `mode` | 'fullscreen' or 'widget' | 'fullscreen' | Display mode |
+| `widget-width` | string | '380px' | Widget width (widget mode only) |
+| `widget-height` | string | '600px' | Widget height (widget mode only) |
+| `primary-color` | string | '#4169E1' | Primary brand color |
+| `primary-color-hover` | string | '#3457C7' | Hover state color |
+| `user-message-bg` | string | '#D6E4FF' | User message background |
+| `bot-message-bg` | string | '#F5F5F5' | Bot message background |
+| `bot-avatar-url` | string | '' | Custom bot avatar image |
+| `background-image-url` | string | '' | Chat background image |
+| `welcome-message` | string | 'How can I help you today?' | Initial welcome message shown when chat is empty |
+| `welcome-subtitle` | string | '' | Optional subtitle text shown below welcome message |
+## API Integration
+The chat widget sends POST requests to the configured api-url with the following payload:
-Request:
 ```json
 {
   "session_id": "string",
@@ -186,108 +173,159 @@ Request:
 }
 ```
-Response:
+Expected response format:
 ```json
 {
-  "response": "string"
+  "response": "string",
+  "faq_used": [
+    {
+      "no.": "1",
+      "question": "What is MySTI?"
+    }
+  ],
+  "suggested_follow_ups": [
+    "What are the main objectives of the program?",
+    "How can companies apply?",
+    "Who is eligible for the MySTI logo?"
+  ]
 }
 ```
-## 🎨 Theming
+**Supported field variations:**
+- `faq_used` or `faqs_used` for related FAQs
+- `suggested_follow_ups` or `suggested_questions` for clickable follow-up questions
-### Built-in Themes
+### Response Behavior
-```html
-<!-- Light mode (default) -->
-<ai-chat theme="light"></ai-chat>
-<!-- Dark mode -->
-<ai-chat theme="dark"></ai-chat>
-```
+- **Related FAQs** - Displayed as non-clickable text references
+- **Suggested Questions** - Displayed as clickable buttons that send the question when clicked
+- **List Formatting** - Messages support automatic list rendering:
+  - Unordered lists: Lines starting with `-`, `*`, or `•`
+  - Ordered lists: Lines starting with `1.`, `2.`, etc.
-### CSS Custom Properties
+### List Formatting Example
-Customize colors by overriding CSS variables:
+Your API can return text with lists:
-```css
-ai-chat {
-  --ai-chat-primary: #2563eb;
-  --ai-chat-background: #ffffff;
-  --ai-chat-text: #09090b;
-  /* ... more variables */
-}
 ```
+MySTI is a government initiative. Key objectives include:
-### Shadow DOM
+1. Stimulating local industry growth
+2. Driving technology-based economic growth
+3. Creating job opportunities
-The component uses Shadow DOM for style encapsulation. To style internal elements, use `::part()`:
-```css
-ai-chat::part(header) {
-  background: linear-gradient(to right, #667eea, #764ba2);
-}
+Key features:
+- Platform for applicants
+- Database of approved goods
+- Reference for procurement
 ```
-## 📚 Examples
+This will be automatically rendered as proper HTML lists.
-Check out the [examples](./examples) directory for complete working examples:
+## Events
-- [Vanilla JavaScript](./examples/vanilla.html)
-- [React](./examples/react.tsx)
-- [Vue](./examples/vue.vue)
-- [Svelte](./examples/svelte.svelte)
-- [Angular](./examples/angular.component.ts)
+The component fires custom events you can listen to:
-## 🌍 Browser Support
+```javascript
+const chat = document.querySelector('ai-chat');
-- Chrome/Edge 90+
-- Firefox 88+
-- Safari 14+
-- Mobile browsers (iOS Safari 14+, Chrome Android)
+// User sends a message
+chat.addEventListener('message-sent', (event) => {
+  console.log('Message sent:', event.detail);
+});
-Requires native Web Components support (Custom Elements v1, Shadow DOM v1).
+// AI responds
+chat.addEventListener('response-received', (event) => {
+  console.log('Response received:', event.detail);
+});
-## 🔄 Migration from React Version
+// Error occurs
+chat.addEventListener('error', (event) => {
+  console.error('Error:', event.detail);
+});
+```
-If you were using the React-only version:
+## Theme Examples
-**Before:**
-```tsx
-import { AIChat } from '@a.izzuddin/ai-chat';
-<AIChat apiUrl="..." />
+### Green Theme (Success)
+```html
+<ai-chat
+  primary-color="#10B981"
+  primary-color-hover="#059669"
+  user-message-bg="#D1FAE5"
+  bot-message-bg="#F3F4F6">
+</ai-chat>
 ```
-**After:**
-```tsx
-import '@a.izzuddin/ai-chat';
-<ai-chat api-url="..." />
+### Purple Theme (Creative)
+```html
+<ai-chat
+  primary-color="#8B5CF6"
+  primary-color-hover="#7C3AED"
+  user-message-bg="#EDE9FE"
+  bot-message-bg="#F5F3FF">
+</ai-chat>
+```
+### Red Theme (Alert)
+```html
+<ai-chat
+  primary-color="#EF4444"
+  primary-color-hover="#DC2626"
+  user-message-bg="#FEE2E2"
+  bot-message-bg="#FEF2F2">
+</ai-chat>
 ```
-Key differences:
-- Component name is lowercase: `<ai-chat>` instead of `<AIChat>`
-- Attributes use kebab-case: `api-url` instead of `apiUrl`
-- Events instead of callback props
+### Orange Theme (Warm)
+```html
+<ai-chat
+  primary-color="#F97316"
+  primary-color-hover="#EA580C"
+  user-message-bg="#FFEDD5"
+  bot-message-bg="#FFF7ED">
+</ai-chat>
+```
-## 🤝 Contributing
+## Responsive Behavior
-Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md).
+The widget automatically adapts to different screen sizes:
-## 📄 License
+- **Desktop (>1024px)**: Full widget size
+- **Tablet (769-1024px)**: Slightly larger widget (400px × 650px)
+- **Small Tablet (481-768px)**: Compact widget (360px × 550px)
+- **Mobile Portrait (≤480px)**: Nearly fullscreen (90vw × 70vh)
+- **Mobile Landscape**: Wider widget (500px × adjusted height)
-MIT © a.izzuddin
+## Development
+### Build for Production
+```bash
+npm run build
+```
+### Run Development Server
+```bash
+npm run dev
+```
+### Lint Code
+```bash
+npm run lint
+```
-## 🔗 Links
+## Browser Support
-- [Documentation](https://github.com/a.izzuddin/ai-chat#readme)
-- [Examples](./examples)
-- [Issue Tracker](https://github.com/a.izzuddin/ai-chat/issues)
-- [npm Package](https://www.npmjs.com/package/@a.izzuddin/ai-chat)
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Modern mobile browsers
-## ⭐ Similar Projects
+## License
-- [@n8n/chat](https://www.npmjs.com/package/@n8n/chat) - n8n's chat widget
-- [Lit](https://lit.dev/) - The library powering this component
+MIT
----
+## Contributing
-**Built with [Lit](https://lit.dev/)** • **Powered by Web Components**
+Contributions are welcome! Please feel free to submit a Pull Request.

package/README.npm.md CHANGED Viewed

@@ -288,6 +288,6 @@ MIT © [Your Name]
 ## Support
-- 📖 [Documentation](https://github.com/a.izzuddin/ai-chat#readme)
-- 🐛 [Issue Tracker](https://github.com/a.izzuddin/ai-chat/issues)
-- 💬 [Discussions](https://github.com/a.izzuddin/ai-chat/discussions)
+- 📖 [Documentation](https://github.com/aiddin/ai-chat#readme)
+- 🐛 [Issue Tracker](https://github.com/aiddin/ai-chat/issues)
+- 💬 [Discussions](https://github.com/aiddin/ai-chat/discussions)