@a.izzuddin/ai-chat 0.2.4 → 0.2.6

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
  1. package/README.md +166 -215
  2. package/README.npm.md +3 -3
  3. package/custom-elements.json +188 -12
  4. package/dist/index.d.mts +55 -1
  5. package/dist/index.d.ts +55 -1
  6. package/dist/index.js +384 -65
  7. package/dist/index.js.map +1 -1
  8. package/dist/index.mjs +384 -65
  9. package/dist/index.mjs.map +1 -1
  10. package/package.json +6 -1
package/README.md CHANGED
@@ -1,293 +1,244 @@
1
- # @a.izzuddin/ai-chat
1
+ # AI Chat Widget
2
2
 
3
- A **framework-agnostic** AI chat web component built with Lit and TypeScript. Works seamlessly with React, Vue, Svelte, Angular, and vanilla JavaScript.
3
+ A modern, customizable chat widget built with Lit web components. Features a clean UI, responsive design, and extensive theming options.
4
4
 
5
- [![npm version](https://img.shields.io/npm/v/@a.izzuddin/ai-chat)](https://www.npmjs.com/package/@a.izzuddin/ai-chat)
6
- [![npm downloads](https://img.shields.io/npm/dm/@a.izzuddin/ai-chat)](https://www.npmjs.com/package/@a.izzuddin/ai-chat)
5
+ ## Features
7
6
 
8
- ## ✨ Features
7
+ - 🎨 **Fully Customizable Theme** - Change colors, backgrounds, and styles
8
+ - 📱 **Responsive Design** - Works seamlessly on desktop, tablet, and mobile
9
+ - 🌓 **Dark Mode Support** - Built-in light and dark themes
10
+ - 📦 **Two Display Modes** - Fullscreen or floating widget
11
+ - 🔧 **Easy Integration** - Simple HTML attributes for configuration
12
+ - ⚡ **Built with Lit** - Fast, lightweight web component
13
+ - 🎯 **TypeScript Support** - Full type safety
9
14
 
10
- - 🌐 **Framework Agnostic** - Works with any framework or no framework
11
- - 🎨 **Beautiful UI** - Modern chat interface with light/dark mode
12
- - ⚡ **Lightweight** - Only ~15KB (gzipped)
13
- - 🔧 **Fully Customizable** - Configure API endpoint, styling, and behavior
14
- - 📱 **Responsive** - Mobile-friendly design
15
- - 🎯 **TypeScript** - Full type safety and IntelliSense
16
- - ♿ **Accessible** - Semantic HTML and ARIA attributes
17
- - 🎪 **Event-Driven** - Listen to messages, responses, and errors
15
+ ## Quick Start
18
16
 
19
- ## 📦 Installation
17
+ ### Installation
20
18
 
21
19
  ```bash
22
- npm install @a.izzuddin/ai-chat
23
- # or
24
- yarn add @a.izzuddin/ai-chat
25
- # or
26
- pnpm add @a.izzuddin/ai-chat
20
+ npm install
21
+ npm run dev
27
22
  ```
28
23
 
29
- ## 🚀 Quick Start
30
-
31
- ### Vanilla JavaScript / HTML
24
+ ### Basic Usage
32
25
 
33
26
  ```html
34
- <!DOCTYPE html>
35
- <html>
36
- <body>
37
- <script type="module">
38
- import '@a.izzuddin/ai-chat';
39
- </script>
40
-
41
- <ai-chat
42
- api-url="https://your-api.com"
43
- session-id="user-123"
44
- title="My AI Assistant">
45
- </ai-chat>
46
- </body>
47
- </html>
27
+ <ai-chat
28
+ api-url="https://your-api-endpoint.com"
29
+ session-id="user-123"
30
+ title="AI Assistant">
31
+ </ai-chat>
48
32
  ```
49
33
 
50
- ### React
34
+ ## Configuration
51
35
 
52
- ```tsx
53
- import '@a.izzuddin/ai-chat';
36
+ ### Display Modes
54
37
 
55
- function App() {
56
- return (
57
- <ai-chat
58
- api-url={process.env.REACT_APP_API_URL}
59
- session-id="user-123"
60
- title="AI Assistant"
61
- />
62
- );
63
- }
38
+ #### Fullscreen Mode (Default)
39
+ ```html
40
+ <ai-chat
41
+ api-url="https://api.example.com"
42
+ session-id="user-123"
43
+ title="AI Assistant"
44
+ mode="fullscreen">
45
+ </ai-chat>
64
46
  ```
65
47
 
66
- ### Vue
67
-
68
- ```vue
69
- <template>
70
- <ai-chat
71
- :api-url="apiUrl"
72
- session-id="user-123"
73
- title="AI Assistant"
74
- />
75
- </template>
76
-
77
- <script setup>
78
- import '@a.izzuddin/ai-chat';
79
- const apiUrl = import.meta.env.VITE_API_URL;
80
- </script>
48
+ #### Widget Mode
49
+ ```html
50
+ <ai-chat
51
+ api-url="https://api.example.com"
52
+ session-id="user-123"
53
+ title="AI Assistant"
54
+ mode="widget"
55
+ widget-width="400px"
56
+ widget-height="650px">
57
+ </ai-chat>
81
58
  ```
82
59
 
83
- ### Svelte
84
-
85
- ```svelte
86
- <script>
87
- import '@a.izzuddin/ai-chat';
88
- export let apiUrl;
89
- </script>
60
+ ### Theme Customization
90
61
 
62
+ #### Custom Colors
63
+ ```html
91
64
  <ai-chat
92
- api-url={apiUrl}
65
+ api-url="https://api.example.com"
93
66
  session-id="user-123"
94
67
  title="AI Assistant"
95
- />
68
+ primary-color="#10B981"
69
+ primary-color-hover="#059669"
70
+ user-message-bg="#D1FAE5"
71
+ bot-message-bg="#F3F4F6">
72
+ </ai-chat>
96
73
  ```
97
74
 
98
- ### Angular
99
-
100
- ```typescript
101
- import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
102
- import '@a.izzuddin/ai-chat';
103
-
104
- @Component({
105
- selector: 'app-root',
106
- template: '<ai-chat api-url="..." session-id="user-123"></ai-chat>',
107
- schemas: [CUSTOM_ELEMENTS_SCHEMA]
108
- })
109
- export class AppComponent {}
75
+ #### Custom Avatars and Background
76
+ ```html
77
+ <ai-chat
78
+ api-url="https://api.example.com"
79
+ session-id="user-123"
80
+ title="AI Assistant"
81
+ bot-avatar-url="/path/to/avatar.png"
82
+ background-image-url="/path/to/background.png">
83
+ </ai-chat>
110
84
  ```
111
85
 
112
- ## 📖 API
86
+ ### Dark Mode
87
+ ```html
88
+ <ai-chat
89
+ api-url="https://api.example.com"
90
+ session-id="user-123"
91
+ title="AI Assistant"
92
+ theme="dark">
93
+ </ai-chat>
94
+ ```
113
95
 
114
- ### Attributes
96
+ ## Available Attributes
115
97
 
116
98
  | Attribute | Type | Default | Description |
117
99
  |-----------|------|---------|-------------|
118
- | `api-url` | `string` | **required** | Your API endpoint URL |
119
- | `session-id` | `string` | `"default-session"` | Session identifier for conversation context |
120
- | `title` | `string` | `"My AI Agent"` | Chat header title |
121
- | `theme` | `"light" \| "dark"` | `"light"` | UI theme |
122
- | `initial-messages` | `Message[]` | `[]` | Pre-populate chat with messages |
100
+ | `api-url` | string | '' | API endpoint URL for chat backend |
101
+ | `session-id` | string | 'default-session' | Unique session identifier |
102
+ | `title` | string | 'My AI Agent' | Chat widget title |
103
+ | `theme` | 'light' or 'dark' | 'light' | Color theme |
104
+ | `mode` | 'fullscreen' or 'widget' | 'fullscreen' | Display mode |
105
+ | `widget-width` | string | '380px' | Widget width (widget mode only) |
106
+ | `widget-height` | string | '600px' | Widget height (widget mode only) |
107
+ | `primary-color` | string | '#4169E1' | Primary brand color |
108
+ | `primary-color-hover` | string | '#3457C7' | Hover state color |
109
+ | `user-message-bg` | string | '#D6E4FF' | User message background |
110
+ | `bot-message-bg` | string | '#F5F5F5' | Bot message background |
111
+ | `bot-avatar-url` | string | '' | Custom bot avatar image |
112
+ | `background-image-url` | string | '' | Chat background image |
113
+
114
+ ## API Integration
115
+
116
+ The chat widget sends POST requests to the configured api-url with the following payload:
123
117
 
124
- ### Properties (JavaScript)
118
+ ```json
119
+ {
120
+ "session_id": "string",
121
+ "question": "string"
122
+ }
123
+ ```
125
124
 
126
- ```javascript
127
- const chat = document.querySelector('ai-chat');
125
+ Expected response format:
128
126
 
129
- // Set properties
130
- chat.apiUrl = 'https://api.example.com';
131
- chat.sessionId = 'user-123';
132
- chat.title = 'Support Bot';
133
- chat.theme = 'dark';
134
- chat.initialMessages = [
135
- { id: '1', role: 'assistant', content: 'Hello! How can I help?' }
136
- ];
127
+ ```json
128
+ {
129
+ "response": "string",
130
+ "faqs_used": [
131
+ {
132
+ "no.": "1",
133
+ "question": "Related question?"
134
+ }
135
+ ]
136
+ }
137
137
  ```
138
138
 
139
- ### Events
139
+ ## Events
140
+
141
+ The component fires custom events you can listen to:
140
142
 
141
143
  ```javascript
142
144
  const chat = document.querySelector('ai-chat');
143
145
 
144
146
  // User sends a message
145
147
  chat.addEventListener('message-sent', (event) => {
146
- console.log('User message:', event.detail);
147
- // event.detail: { id: string, role: 'user', content: string }
148
+ console.log('Message sent:', event.detail);
148
149
  });
149
150
 
150
151
  // AI responds
151
152
  chat.addEventListener('response-received', (event) => {
152
- console.log('AI response:', event.detail);
153
- // event.detail: { id: string, role: 'assistant', content: string }
153
+ console.log('Response received:', event.detail);
154
154
  });
155
155
 
156
156
  // Error occurs
157
157
  chat.addEventListener('error', (event) => {
158
- console.error('Chat error:', event.detail);
159
- // event.detail: Error object
158
+ console.error('Error:', event.detail);
160
159
  });
161
160
  ```
162
161
 
163
- ### TypeScript Types
164
-
165
- ```typescript
166
- import type { Message } from '@a.izzuddin/ai-chat';
162
+ ## Theme Examples
167
163
 
168
- interface Message {
169
- id: string;
170
- role: 'user' | 'assistant';
171
- content: string;
172
- }
164
+ ### Green Theme (Success)
165
+ ```html
166
+ <ai-chat
167
+ primary-color="#10B981"
168
+ primary-color-hover="#059669"
169
+ user-message-bg="#D1FAE5"
170
+ bot-message-bg="#F3F4F6">
171
+ </ai-chat>
173
172
  ```
174
173
 
175
- ## 🔌 Backend API Requirements
176
-
177
- Your API must implement this endpoint:
178
-
179
- **POST `/ask`**
180
-
181
- Request:
182
- ```json
183
- {
184
- "session_id": "string",
185
- "question": "string"
186
- }
174
+ ### Purple Theme (Creative)
175
+ ```html
176
+ <ai-chat
177
+ primary-color="#8B5CF6"
178
+ primary-color-hover="#7C3AED"
179
+ user-message-bg="#EDE9FE"
180
+ bot-message-bg="#F5F3FF">
181
+ </ai-chat>
187
182
  ```
188
183
 
189
- Response:
190
- ```json
191
- {
192
- "response": "string"
193
- }
184
+ ### Red Theme (Alert)
185
+ ```html
186
+ <ai-chat
187
+ primary-color="#EF4444"
188
+ primary-color-hover="#DC2626"
189
+ user-message-bg="#FEE2E2"
190
+ bot-message-bg="#FEF2F2">
191
+ </ai-chat>
194
192
  ```
195
193
 
196
- ## 🎨 Theming
197
-
198
- ### Built-in Themes
199
-
194
+ ### Orange Theme (Warm)
200
195
  ```html
201
- <!-- Light mode (default) -->
202
- <ai-chat theme="light"></ai-chat>
203
-
204
- <!-- Dark mode -->
205
- <ai-chat theme="dark"></ai-chat>
196
+ <ai-chat
197
+ primary-color="#F97316"
198
+ primary-color-hover="#EA580C"
199
+ user-message-bg="#FFEDD5"
200
+ bot-message-bg="#FFF7ED">
201
+ </ai-chat>
206
202
  ```
207
203
 
208
- ### CSS Custom Properties
204
+ ## Responsive Behavior
209
205
 
210
- Customize colors by overriding CSS variables:
206
+ The widget automatically adapts to different screen sizes:
211
207
 
212
- ```css
213
- ai-chat {
214
- --ai-chat-primary: #2563eb;
215
- --ai-chat-background: #ffffff;
216
- --ai-chat-text: #09090b;
217
- /* ... more variables */
218
- }
219
- ```
220
-
221
- ### Shadow DOM
208
+ - **Desktop (>1024px)**: Full widget size
209
+ - **Tablet (769-1024px)**: Slightly larger widget (400px × 650px)
210
+ - **Small Tablet (481-768px)**: Compact widget (360px × 550px)
211
+ - **Mobile Portrait (≤480px)**: Nearly fullscreen (90vw × 70vh)
212
+ - **Mobile Landscape**: Wider widget (500px × adjusted height)
222
213
 
223
- The component uses Shadow DOM for style encapsulation. To style internal elements, use `::part()`:
214
+ ## Development
224
215
 
225
- ```css
226
- ai-chat::part(header) {
227
- background: linear-gradient(to right, #667eea, #764ba2);
228
- }
216
+ ### Build for Production
217
+ ```bash
218
+ npm run build
229
219
  ```
230
220
 
231
- ## 📚 Examples
232
-
233
- Check out the [examples](./examples) directory for complete working examples:
234
-
235
- - [Vanilla JavaScript](./examples/vanilla.html)
236
- - [React](./examples/react.tsx)
237
- - [Vue](./examples/vue.vue)
238
- - [Svelte](./examples/svelte.svelte)
239
- - [Angular](./examples/angular.component.ts)
240
-
241
- ## 🌍 Browser Support
242
-
243
- - Chrome/Edge 90+
244
- - Firefox 88+
245
- - Safari 14+
246
- - Mobile browsers (iOS Safari 14+, Chrome Android)
247
-
248
- Requires native Web Components support (Custom Elements v1, Shadow DOM v1).
249
-
250
- ## 🔄 Migration from React Version
251
-
252
- If you were using the React-only version:
253
-
254
- **Before:**
255
- ```tsx
256
- import { AIChat } from '@a.izzuddin/ai-chat';
257
- <AIChat apiUrl="..." />
221
+ ### Run Development Server
222
+ ```bash
223
+ npm run dev
258
224
  ```
259
225
 
260
- **After:**
261
- ```tsx
262
- import '@a.izzuddin/ai-chat';
263
- <ai-chat api-url="..." />
226
+ ### Lint Code
227
+ ```bash
228
+ npm run lint
264
229
  ```
265
230
 
266
- Key differences:
267
- - Component name is lowercase: `<ai-chat>` instead of `<AIChat>`
268
- - Attributes use kebab-case: `api-url` instead of `apiUrl`
269
- - Events instead of callback props
270
-
271
- ## 🤝 Contributing
272
-
273
- Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md).
274
-
275
- ## 📄 License
276
-
277
- MIT © a.izzuddin
278
-
279
- ## 🔗 Links
231
+ ## Browser Support
280
232
 
281
- - [Documentation](https://github.com/a.izzuddin/ai-chat#readme)
282
- - [Examples](./examples)
283
- - [Issue Tracker](https://github.com/a.izzuddin/ai-chat/issues)
284
- - [npm Package](https://www.npmjs.com/package/@a.izzuddin/ai-chat)
233
+ - Chrome/Edge (latest)
234
+ - Firefox (latest)
235
+ - Safari (latest)
236
+ - Modern mobile browsers
285
237
 
286
- ## ⭐ Similar Projects
238
+ ## License
287
239
 
288
- - [@n8n/chat](https://www.npmjs.com/package/@n8n/chat) - n8n's chat widget
289
- - [Lit](https://lit.dev/) - The library powering this component
240
+ MIT
290
241
 
291
- ---
242
+ ## Contributing
292
243
 
293
- **Built with [Lit](https://lit.dev/)** • **Powered by Web Components**
244
+ Contributions are welcome! Please feel free to submit a Pull Request.
package/README.npm.md CHANGED
@@ -288,6 +288,6 @@ MIT © [Your Name]
288
288
 
289
289
  ## Support
290
290
 
291
- - 📖 [Documentation](https://github.com/a.izzuddin/ai-chat#readme)
292
- - 🐛 [Issue Tracker](https://github.com/a.izzuddin/ai-chat/issues)
293
- - 💬 [Discussions](https://github.com/a.izzuddin/ai-chat/discussions)
291
+ - 📖 [Documentation](https://github.com/aiddin/ai-chat#readme)
292
+ - 🐛 [Issue Tracker](https://github.com/aiddin/ai-chat/issues)
293
+ - 💬 [Discussions](https://github.com/aiddin/ai-chat/discussions)