quikchat 1.1.12 → 1.1.14

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 (14) hide show
  1. package/README.md +291 -151
  2. package/dist/quikchat.cjs.js +143 -8
  3. package/dist/quikchat.cjs.js.map +1 -1
  4. package/dist/quikchat.cjs.min.js +1 -1
  5. package/dist/quikchat.cjs.min.js.map +1 -1
  6. package/dist/quikchat.esm.js +143 -8
  7. package/dist/quikchat.esm.js.map +1 -1
  8. package/dist/quikchat.esm.min.js +1 -1
  9. package/dist/quikchat.esm.min.js.map +1 -1
  10. package/dist/quikchat.umd.js +143 -8
  11. package/dist/quikchat.umd.js.map +1 -1
  12. package/dist/quikchat.umd.min.js +1 -1
  13. package/dist/quikchat.umd.min.js.map +1 -1
  14. package/package.json +1 -1
package/README.md CHANGED
@@ -2,218 +2,358 @@
2
2
  [![NPM version](https://img.shields.io/npm/v/quikchat.svg?style=flat-square)](https://www.npmjs.com/package/quikchat)
3
3
  ![CI](https://github.com/deftio/quikchat/actions/workflows/ci.yml/badge.svg)
4
4
 
5
- # QuikChat (js)
5
+ # QuikChat
6
6
 
7
- Quikchat is a vanilla (no dependancies) JavaScript chat control that can be easily integrated into web applications. It provides a customizable chat interface with support for hiding and showing a title area and the input area.
7
+ > Zero-dependency JavaScript chat widget for modern web applications
8
8
 
9
- [Article on Using Quickchat](https://medium.com/gitconnected/quikchat-4be8d4a849e5?sk=ac745ae60a3521a9fbca6b748d4da48a)
9
+ QuikChat is a lightweight, highly customizable chat interface that integrates seamlessly with any web project. Built with vanilla JavaScript, it provides powerful features for LLM applications, real-time chat, and interactive messaging experiences.
10
10
 
11
- ## Features
11
+ **🚀 [Live Demo](https://deftio.github.io/quikchat/examples/example_umd.html) | 📚 [API Reference](API-REFERENCE.md) | 🛠 [Developer Guide](DEVELOPER-GUIDE.md)**
12
12
 
13
- * Themeable with CSS (examples for light and dark)
14
- * Responsive design for various screen sizes and resizes with parent container
15
- * Hideable/Showable Title and Text Entry areas allows flexibility of usage
16
- * Full message history storage and retrieval (save and resume full chats)
17
- * History can be fed directly to OpenAI / Mistral / Ollama compatible APIs for context aware chats
18
- * Available via NPM, CDN or source via github
19
- * Provided in UMD and ESM formats (+ minified)
20
- * Multiple separate instances can run on a single page
21
- * Multiple users can be in a chat
22
- * Messages can be searched, appended to (streamed token completion), replaced, or removed.
23
- * Left / Right / Center support of individual users
24
- * Callback for all message events (to monitor chat)
25
- * Example backends for Python FastApi and Nodejs (see examples for working full projects)
26
13
 
27
- ## Demo & Examples
28
14
 
29
- [Simple Demo](https://deftio.github.io/quikchat/examples/example_umd.html)
15
+ ## ✨ Key Features
30
16
 
31
- [List of Examples on Github](https://deftio.github.io/quikchat/examples/index.html)
17
+ - **🚫 Zero Dependencies** - Pure vanilla JavaScript, no frameworks required
18
+ - **🎨 Fully Customizable** - Complete CSS theming system with multi-instance support
19
+ - **🤖 LLM Ready** - Built-in support for OpenAI, Anthropic, Ollama, and streaming responses
20
+ - **📱 Responsive Design** - Adapts to any screen size and container dimensions
21
+ - **⚡ High Performance** - Efficient message handling and memory management
22
+ - **👁 Advanced Visibility** - Individual and group-based message control (v1.1.13+)
23
+ - **🏷 Tagged Messages** - Powerful tagging system for message organization (v1.1.14+)
24
+ - **💾 Full History Control** - Save, load, and restore complete chat sessions
25
+ - **🔧 Developer Friendly** - TypeScript-ready with comprehensive API
32
26
 
33
27
 
34
- Full Examples are in the repo examples folder (relative link):
35
- [Example Code and Demo](./examples/index.html).
36
28
 
37
- Examples include using ESM, UMD modules, theming, running multiple chats on the same page, and integration with LLM providers such as Ollama, LMStudio, OpenAI compatible providers.
29
+ ## 🚀 Quick Start
38
30
 
39
- ## Installation
40
-
41
- To use quikchat in your project, follow these steps:
42
-
43
- Include the quikchat.js JavaScript file in your project.
44
- Link the quikchat.css stylesheet to style the chat interface.
45
- html
31
+ Get a working chat interface in under 60 seconds:
46
32
 
33
+ ### Via CDN
47
34
  ```html
48
- <script src="./path/to/quikchat.umd.min.js"></script>
49
- <link rel="stylesheet" href="./path/to/quikchat.css">
35
+ <!DOCTYPE html>
36
+ <html>
37
+ <head>
38
+ <link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css">
39
+ </head>
40
+ <body>
41
+ <div id="chat" style="width: 100%; height: 400px;"></div>
42
+
43
+ <script src="https://unpkg.com/quikchat"></script>
44
+ <script>
45
+ const chat = new quikchat('#chat', (instance, message) => {
46
+ // Echo user message
47
+ instance.messageAddNew(message, 'You', 'right');
48
+
49
+ // Add bot response
50
+ setTimeout(() => {
51
+ instance.messageAddNew('Thanks for your message!', 'Bot', 'left');
52
+ }, 1000);
53
+ });
54
+
55
+ // Add welcome message
56
+ chat.messageAddNew('Hello! How can I help you today?', 'Bot', 'left');
57
+ </script>
58
+ </body>
59
+ </html>
50
60
  ```
51
61
 
52
- ### use quikchat Via CDN
53
-
54
- ```html
55
- <script src="https://unpkg.com/quikchat"></script>
56
- <link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css" />
62
+ ### Via NPM
63
+ ```bash
64
+ npm install quikchat
57
65
  ```
58
66
 
59
- Or import as a module:
60
-
61
67
  ```javascript
62
- import quikchat from '../dist/quikchat.esm.min.js';
63
-
64
- document.addEventListener('DOMContentLoaded', () => {
65
- const parentDiv = document.querySelector('#chatContainerInstance');
66
- window.chatBox = new quikchat(parentDiv,
67
- (chat, msg) => {
68
- chat.messageAddNew(msg, 'me', 'right'); // echo the message to the chat area
69
-
70
- // example of a bot response using the built-in lorem ipsum generator
71
- const botResponse = quikchat.loremIpsum();
72
- chat.messageAddNew(botResponse, 'bot', 'left');
73
- },
74
- { // options
75
- theme: 'quikchat-theme-light',
76
- titleArea: { title: 'QuikChatJS', align: 'left', show: true },
77
- });
78
- chatBox.messageAddNew('Hello, how are you?', 'bot', 'left');
79
- chatBox.messageAddNew('I am fine, thank you.', 'user', 'right');
80
- chatBox.messageAddNew('How can I help you today?', 'bot', 'left');
81
- chatBox.changeTheme("quikchat-theme-light");
82
- console.log("quikchat version: "+quikchat.version().version);
68
+ import quikchat from 'quikchat';
69
+ import 'quikchat/dist/quikchat.css';
83
70
 
71
+ const chat = new quikchat('#chat-container', (instance, message) => {
72
+ // Your message handling logic
73
+ console.log('User said:', message);
84
74
  });
85
75
  ```
86
76
 
87
- Create a container element in your HTML where you want the chat interface to appear. The quikchat widget will take 100% of the paretn container height and width. If the parent container width or height is not specified the quikchat widget may grow as content is added. If the parent container is resized, quikchat will resize with the parent container.
88
77
 
78
+
79
+ ## 📦 Installation Options
80
+
81
+ ### NPM Package
82
+ ```bash
83
+ npm install quikchat
84
+ ```
85
+
86
+ ### CDN (Latest Version)
89
87
  ```html
90
- <style>
91
- #chat-container {width: 100%; height: 50vh;} /* use any width / height as appropriate for your app */
92
- </style>
93
- <div id="chat-container"></div>
88
+ <!-- CSS -->
89
+ <link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css">
90
+
91
+ <!-- JavaScript -->
92
+ <script src="https://unpkg.com/quikchat"></script>
94
93
  ```
95
94
 
96
- Initialize quikchat in your JavaScript code by providing the container element and a callback function for message events:
95
+ ### Direct Download
96
+ Download the latest release from [GitHub Releases](https://github.com/deftio/quikchat/releases)
97
+
98
+
99
+
100
+ ## 🆕 What's New in v1.1.14
97
101
 
98
- See /examples for full working code.
102
+ ### 🏷 Tagged Message System
103
+ Group and control message visibility with powerful tagging:
99
104
 
100
105
  ```javascript
101
- chat = new quikchat(
102
- "#chat-container",//a css selector such as "#chat-container" or DOM element
103
- (chat, msg) => { // this callback triggered when user hits the Send
104
- // messages are not automatically echoed.
105
- // this allows filtering of the message before posting.
106
- chat.messageAddNew(msg, 'me', 'right'); // echo msg to chat area
107
- // now call an LLM or do other actions with msg
108
- // ... callLLM(msg) ... do other logic if needed.
109
- // or callLLM(chat.historyGet()); // pass full history (can also filter)
110
- },
111
- {
112
- theme: 'quikchat-theme-light', // set theme, see quikchat.css
113
- titleArea: { title: 'My Chat', align: 'left', show: true }, // internal title area if desired
114
- });
106
+ // Add messages with tags
107
+ chat.messageAddNew('System initialized', 'System', 'center', 'system', true, true, ['system', 'startup']);
115
108
 
116
- // Add a message at any point not just from callback
117
- chat.messageAddNew('Hello!', 'You', 'left'); // should appear left justified
118
- chat.messageAddNew('Hello!', 'Me', 'right'); // should appear right justified
109
+ // Control visibility by tag
110
+ chat.setTagVisibility('system', false); // Hide all system messages
111
+ chat.setTagVisibility('system', true); // Show all system messages
119
112
 
113
+ // Get active tags
114
+ const tags = chat.getActiveTags(); // ['system', 'startup', 'user']
115
+ ```
116
+
117
+ ### 🎯 Instance Scoping
118
+ Multiple chat instances with different styling and behavior:
119
+
120
+ ```javascript
121
+ const salesChat = new quikchat('#sales', handler, {
122
+ theme: 'quikchat-theme-light',
123
+ instanceClass: 'sales-chat'
124
+ });
120
125
 
121
- //... other logic
122
- let messageHistory = chat.historyGet(); // get all the messages (see docs for filters)
123
- console.log(messageHistory); // do something with messages
126
+ const supportChat = new quikchat('#support', handler, {
127
+ theme: 'quikchat-theme-dark',
128
+ instanceClass: 'support-chat'
129
+ });
130
+ ```
124
131
 
125
- // show / hide the title area
126
- chat.titleAreaHide(); // hides the title area for a bare chat
132
+ ### 👁 Enhanced Visibility Controls (v1.1.13+)
133
+ Fine-grained control over message display:
127
134
 
128
- // hide the input area
129
- chat.inputAreaHide(); // hides the input area so chat is now just a message stream.
135
+ ```javascript
136
+ // Hide individual messages
137
+ chat.messageSetVisibility(messageId, false);
130
138
 
131
- // change themes at any time
132
- chat.changeTheme("quikchat-theme-dark"); // change theme on the fly (see quikchat.css for examples)
139
+ // Check visibility status
140
+ const isVisible = chat.messageGetVisibility(messageId);
133
141
  ```
134
142
 
135
- ## Theming
143
+ **[View Complete Changelog](https://github.com/deftio/quikchat/releases)**
144
+
145
+
146
+
147
+ ## 🎨 Theming & Customization
136
148
 
137
- QuikChat allows theming using CSS of all the messages, and user area, and overal widget.
149
+ QuikChat includes beautiful built-in themes and supports complete customization:
138
150
 
139
- Below is the prebuilt 'light' theme. To change the theme, make a new set of classes with different values but the same css selector naming (e.g. change "quikchat-theme-light" to "my-theme") and save as a style. Then pass the "my-theme" to the constructor or to the changeTheme() function.
151
+ ```javascript
152
+ // Use built-in themes
153
+ const chat = new quikchat('#chat', handler, {
154
+ theme: 'quikchat-theme-dark' // or 'quikchat-theme-light'
155
+ });
140
156
 
141
- Themes can be changed at anytime by calling
142
- myChatWidget.changeTheme(newTheme) where myChatWidget is the instance of your widget.
157
+ // Switch themes dynamically
158
+ chat.changeTheme('quikchat-theme-light');
159
+ ```
143
160
 
144
- If several widgets are on the same page, each can have a separate theme.
161
+ ### Custom Themes
162
+ Create your own themes with CSS:
145
163
 
146
164
  ```css
147
- /* quikchat theme light */
148
- .quikchat-theme-light {
149
- border: 1px solid #cccccc;
150
- border-radius: 10px;
151
- background-color: #f9f9f9;
152
- }
153
-
154
- .quikchat-theme-light .quikchat-title-area {
155
- padding: 8px;
156
- color: #333;
157
- }
158
-
159
- .quikchat-theme-light .quikchat-messages-area {
160
- background-color: #ffffffe2;
161
- color: #333;
162
- }
163
-
164
- /* support for alternating row styles */
165
- .quikchat-theme-light .quikchat-messages-area-alt .quikchat-message:nth-child(odd) {
166
- background-color: #fffffff0;
167
- color: #005662;
165
+ .my-custom-theme {
166
+ border: 2px solid #3b82f6;
167
+ border-radius: 12px;
168
+ font-family: 'SF Pro Display', sans-serif;
168
169
  }
169
- .quikchat-theme-light .quikchat-messages-area-alt .quikchat-message:nth-child(even) {
170
- background-color: #eeeeeee9;
171
- color: #353535;
170
+
171
+ .my-custom-theme .quikchat-message-content {
172
+ border-radius: 18px;
173
+ padding: 12px 16px;
172
174
  }
173
175
 
174
- /* input area / text entry / send button */
175
- .quikchat-theme-light .quikchat-input-area {
176
- background-color: #f9f9f9;
177
- border-bottom-left-radius : 10px;
178
- border-bottom-right-radius : 10px;
176
+ /* Apply to chat */
177
+ const chat = new quikchat('#chat', handler, {
178
+ theme: 'my-custom-theme'
179
+ });
180
+ ```
181
+
182
+ **📖 [Complete Theming Guide](DEVELOPER-GUIDE.md#theming-guide)**
183
+
184
+
185
+
186
+ ## 🤖 LLM Integration Examples
187
+
188
+ ### OpenAI Integration
189
+ ```javascript
190
+ async function handleMessage(chat, message) {
191
+ chat.messageAddNew(message, 'You', 'right');
192
+
193
+ const response = await fetch('https://api.openai.com/v1/chat/completions', {
194
+ method: 'POST',
195
+ headers: {
196
+ 'Authorization': `Bearer ${API_KEY}`,
197
+ 'Content-Type': 'application/json'
198
+ },
199
+ body: JSON.stringify({
200
+ model: 'gpt-4',
201
+ messages: formatChatHistory(chat.historyGetAllCopy(), message)
202
+ })
203
+ });
204
+
205
+ const data = await response.json();
206
+ chat.messageAddNew(data.choices[0].message.content, 'Assistant', 'left');
179
207
  }
208
+ ```
180
209
 
181
- .quikchat-theme-light .quikchat-input-textbox {
182
- background-color: #ffffff;
183
- border: 1px solid #ccc;
184
- border-radius: 4px;
185
- font-size: 14px;
186
- color: #333;
210
+ ### Streaming Responses
211
+ ```javascript
212
+ // Create message for streaming
213
+ const botMsgId = chat.messageAddNew('', 'Bot', 'left');
214
+
215
+ // Append content as it arrives
216
+ streamingAPI.onChunk(chunk => {
217
+ chat.messageAppendContent(botMsgId, chunk);
218
+ });
219
+ ```
220
+
221
+ **🛠 [Complete LLM Integration Guide](DEVELOPER-GUIDE.md#llm-integration-best-practices)**
222
+
223
+
224
+
225
+ ## 🏗 Framework Integration
226
+
227
+ ### React
228
+ ```jsx
229
+ function ChatComponent() {
230
+ const chatRef = useRef(null);
231
+ const instanceRef = useRef(null);
232
+
233
+ useEffect(() => {
234
+ instanceRef.current = new quikchat(chatRef.current, handleMessage);
235
+ }, []);
236
+
237
+ return <div ref={chatRef} style={{ height: '400px' }} />;
187
238
  }
188
-
189
- .quikchat-theme-light .quikchat-input-send-btn {
190
- background-color: #4caf50;
191
- color: white;
192
- border: none;
193
- border-radius: 4px;
239
+ ```
240
+
241
+ ### Vue
242
+ ```vue
243
+ <template>
244
+ <div ref="chatContainer" class="chat-container"></div>
245
+ </template>
246
+
247
+ <script>
248
+ import quikchat from 'quikchat';
249
+
250
+ export default {
251
+ mounted() {
252
+ this.chat = new quikchat(this.$refs.chatContainer, this.handleMessage);
253
+ }
194
254
  }
255
+ </script>
195
256
  ```
196
257
 
197
- ## Building from Source
258
+ **⚛️ [Framework Integration Examples](DEVELOPER-GUIDE.md#frontend-framework-integration)**
259
+
260
+
261
+
262
+ ## 📖 Documentation
263
+
264
+ | Document | Description |
265
+ |-|-|
266
+ | **[API Reference](API-REFERENCE.md)** | Complete technical reference for all methods and options |
267
+ | **[Developer Guide](DEVELOPER-GUIDE.md)** | Practical recipes and advanced patterns |
268
+ | **[Examples](examples/)** | Working code examples and demos |
269
+ | **[Live Demo](https://deftio.github.io/quikchat/examples/)** | Interactive examples and showcase |
270
+
271
+
272
+
273
+ ## 🌟 Examples & Demos
274
+
275
+ - **[Basic Chat](https://deftio.github.io/quikchat/examples/example_umd.html)** - Simple chat interface
276
+ - **[LLM Integration](examples/openai.html)** - OpenAI GPT integration
277
+ - **[Multi-Instance](examples/dual-chatrooms.html)** - Multiple chats on one page
278
+ - **[Visibility Controls](examples/hidden_message.html)** - Message visibility features
279
+ - **[Theme Showcase](https://deftio.github.io/quikchat/examples/)** - Light and dark themes
280
+ - **[React Integration](examples/quikchat-react.html)** - React component example
281
+ - **[Backend Examples](examples/)** - FastAPI and Node.js backends
282
+
283
+ **📂 [Browse All Examples](examples/index.html)**
284
+
198
285
 
199
- quikchat is built with [rollup.js](https://rollupjs.org/).
200
286
 
201
- Make sure to run npm install. Then run npm run build.
287
+ ## 🚀 Performance
202
288
 
203
- Note that at run time quikchat has no dependancies, but at build time several tools are used for packing and minifying code.
289
+ QuikChat is built for production use with excellent performance characteristics:
204
290
 
205
- ## Testing
291
+ - **Lightweight**: ~25KB minified + gzipped
292
+ - **Fast**: Sub-millisecond message rendering
293
+ - **Scalable**: Handles thousands of messages efficiently
294
+ - **Memory Efficient**: Automatic cleanup and optimization
206
295
 
207
- quikchat is tested with the jest framwork. To run unit tests and see coverage run:
296
+ **📊 [Performance Optimization Guide](DEVELOPER-GUIDE.md#performance-optimization)**
208
297
 
298
+
299
+
300
+ ## 🛠 Building from Source
301
+
302
+ ```bash
303
+ # Clone repository
304
+ git clone https://github.com/deftio/quikchat.git
305
+ cd quikchat
306
+
307
+ # Install dependencies
308
+ npm install
309
+
310
+ # Build for production
311
+ npm run build
312
+
313
+ # Run tests
314
+ npm test
315
+
316
+ # Start development server
317
+ npm run dev
318
+ ```
319
+
320
+ **Requirements**: Node.js 14+ and npm 6+
321
+
322
+
323
+
324
+ ## 🤝 Contributing
325
+
326
+ We welcome contributions! Here's how you can help:
327
+
328
+ 1. **🐛 Report Issues** - Found a bug? [Open an issue](https://github.com/deftio/quikchat/issues)
329
+ 2. **💡 Feature Requests** - Have an idea? We'd love to hear it
330
+ 3. **🔧 Code Contributions** - Submit pull requests for bug fixes or new features
331
+ 4. **📖 Documentation** - Help improve our guides and examples
332
+ 5. **🌟 Share Examples** - Show us what you've built with QuikChat
333
+
334
+ ### Development Setup
209
335
  ```bash
210
- npm run test
336
+ git clone https://github.com/deftio/quikchat.git
337
+ cd quikchat
338
+ npm install
339
+ npm run dev
211
340
  ```
212
341
 
213
- ## License
342
+ **📋 [Contributing Guidelines](CONTRIBUTING.md)**
343
+
344
+
345
+
346
+ ## 📄 License
347
+
348
+ QuikChat is licensed under the [BSD-2-Clause License](LICENSE.txt).
349
+
350
+
214
351
 
215
- quikchat is licensed under the BSD-2 License.
352
+ ## 🔗 Links
216
353
 
217
- ## Home Page
354
+ - **📦 [NPM Package](https://www.npmjs.com/package/quikchat)**
355
+ - **🐙 [GitHub Repository](https://github.com/deftio/quikchat)**
356
+ - **🚀 [Live Examples](https://deftio.github.io/quikchat/examples/)**
357
+ - **📖 [Medium Article](https://medium.com/gitconnected/quikchat-4be8d4a849e5)**
358
+ - **💬 [Issues & Support](https://github.com/deftio/quikchat/issues)**
218
359
 
219
- [quikchat homepage and source code](https://github.com/deftio/quikchat)