quikchat 1.1.13 → 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 +279 -188
  2. package/dist/quikchat.cjs.js +53 -6
  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 +53 -6
  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 +53 -6
  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,267 +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
31
+ Get a working chat interface in under 60 seconds:
40
32
 
41
- To use quikchat in your project, follow these steps:
33
+ ### Via CDN
34
+ ```html
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>
60
+ ```
42
61
 
43
- Include the quikchat.js JavaScript file in your project.
44
- Link the quikchat.css stylesheet to style the chat interface.
45
- html
62
+ ### Via NPM
63
+ ```bash
64
+ npm install quikchat
65
+ ```
46
66
 
47
- ```html
48
- <script src="./path/to/quikchat.umd.min.js"></script>
49
- <link rel="stylesheet" href="./path/to/quikchat.css">
67
+ ```javascript
68
+ import quikchat from 'quikchat';
69
+ import 'quikchat/dist/quikchat.css';
70
+
71
+ const chat = new quikchat('#chat-container', (instance, message) => {
72
+ // Your message handling logic
73
+ console.log('User said:', message);
74
+ });
50
75
  ```
51
76
 
52
- ### use quikchat Via CDN
53
77
 
78
+
79
+ ## 📦 Installation Options
80
+
81
+ ### NPM Package
82
+ ```bash
83
+ npm install quikchat
84
+ ```
85
+
86
+ ### CDN (Latest Version)
54
87
  ```html
88
+ <!-- CSS -->
89
+ <link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css">
90
+
91
+ <!-- JavaScript -->
55
92
  <script src="https://unpkg.com/quikchat"></script>
56
- <link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css" />
57
93
  ```
58
94
 
59
- Or import as a module:
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
101
+
102
+ ### 🏷 Tagged Message System
103
+ Group and control message visibility with powerful tagging:
60
104
 
61
105
  ```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);
106
+ // Add messages with tags
107
+ chat.messageAddNew('System initialized', 'System', 'center', 'system', true, true, ['system', 'startup']);
83
108
 
84
- });
109
+ // Control visibility by tag
110
+ chat.setTagVisibility('system', false); // Hide all system messages
111
+ chat.setTagVisibility('system', true); // Show all system messages
112
+
113
+ // Get active tags
114
+ const tags = chat.getActiveTags(); // ['system', 'startup', 'user']
85
115
  ```
86
116
 
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.
117
+ ### 🎯 Instance Scoping
118
+ Multiple chat instances with different styling and behavior:
88
119
 
89
- ```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>
94
- ```
120
+ ```javascript
121
+ const salesChat = new quikchat('#sales', handler, {
122
+ theme: 'quikchat-theme-light',
123
+ instanceClass: 'sales-chat'
124
+ });
95
125
 
96
- Initialize quikchat in your JavaScript code by providing the container element and a callback function for message events:
126
+ const supportChat = new quikchat('#support', handler, {
127
+ theme: 'quikchat-theme-dark',
128
+ instanceClass: 'support-chat'
129
+ });
130
+ ```
97
131
 
98
- See /examples for full working code.
132
+ ### 👁 Enhanced Visibility Controls (v1.1.13+)
133
+ Fine-grained control over message display:
99
134
 
100
135
  ```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
- });
115
-
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
119
-
120
-
121
- //... other logic
122
- let messageHistory = chat.historyGet(); // get all the messages (see docs for filters)
123
- console.log(messageHistory); // do something with messages
124
-
125
- // show / hide the title area
126
- chat.titleAreaHide(); // hides the title area for a bare chat
127
-
128
- // hide the input area
129
- chat.inputAreaHide(); // hides the input area so chat is now just a message stream.
130
-
131
- // change themes at any time
132
- chat.changeTheme("quikchat-theme-dark"); // change theme on the fly (see quikchat.css for examples)
136
+ // Hide individual messages
137
+ chat.messageSetVisibility(messageId, false);
138
+
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
+
136
146
 
137
- QuikChat allows theming using CSS of all the messages, and user area, and overal widget.
147
+ ## 🎨 Theming & Customization
138
148
 
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.
149
+ QuikChat includes beautiful built-in themes and supports complete customization:
140
150
 
141
- Themes can be changed at anytime by calling
142
- myChatWidget.changeTheme(newTheme) where myChatWidget is the instance of your widget.
151
+ ```javascript
152
+ // Use built-in themes
153
+ const chat = new quikchat('#chat', handler, {
154
+ theme: 'quikchat-theme-dark' // or 'quikchat-theme-light'
155
+ });
143
156
 
144
- If several widgets are on the same page, each can have a separate theme.
157
+ // Switch themes dynamically
158
+ chat.changeTheme('quikchat-theme-light');
159
+ ```
160
+
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;
165
+ .my-custom-theme {
166
+ border: 2px solid #3b82f6;
167
+ border-radius: 12px;
168
+ font-family: 'SF Pro Display', sans-serif;
157
169
  }
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;
168
- }
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
+ ```
209
+
210
+ ### Streaming Responses
211
+ ```javascript
212
+ // Create message for streaming
213
+ const botMsgId = chat.messageAddNew('', 'Bot', 'left');
180
214
 
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;
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)**
198
259
 
199
- quikchat is built with [rollup.js](https://rollupjs.org/).
200
260
 
201
- Make sure to run npm install. Then run npm run build.
202
261
 
203
- Note that at run time quikchat has no dependancies, but at build time several tools are used for packing and minifying code.
262
+ ## 📖 Documentation
204
263
 
205
- ## Testing
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 |
206
270
 
207
- quikchat is tested with the jest framwork. To run unit tests and see coverage run:
208
271
 
209
- ```bash
210
- npm run test
211
- ```
212
272
 
213
- ## License
273
+ ## 🌟 Examples & Demos
214
274
 
215
- quikchat is licensed under the BSD-2 License.
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
216
282
 
217
- ## Home Page
283
+ **📂 [Browse All Examples](examples/index.html)**
218
284
 
219
- [quikchat homepage and source code](https://github.com/deftio/quikchat)
220
285
 
221
- ## New Features
222
286
 
223
- - `role` (string): The role of the message sender (e.g., "user", "agent"). Defaults to "user".
224
- - `scrollIntoView` (boolean): If true, the chat will scroll to the bottom after the message is added. Defaults to true.
287
+ ## 🚀 Performance
225
288
 
226
- **Example:**
227
- ```javascript
228
- myChat.messageAddNew("Hello world!", "Alice", "left", "user");
289
+ QuikChat is built for production use with excellent performance characteristics:
290
+
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
295
+
296
+ **📊 [Performance Optimization Guide](DEVELOPER-GUIDE.md#performance-optimization)**
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
229
318
  ```
230
319
 
231
- ### `messageAddFull(input)`
320
+ **Requirements**: Node.js 14+ and npm 6+
232
321
 
233
- Adds a new message with a comprehensive set of options.
234
322
 
235
- - `input` (object): An object containing message properties:
236
- - `content` (string): The HTML content of the message.
237
- - `userString` (string): The name to display for the user.
238
- - `align` (string): `left`, `right`, or `center`.
239
- - `role` (string): The role of the sender.
240
- - `userID` (number): A numeric ID for the user.
241
- - `timestamp` (string|boolean): An ISO string for the timestamp, or `false`.
242
- - `updatedtime` (string|boolean): An ISO string for the last update time, or `false`.
243
- - `scrollIntoView` (boolean): Whether to scroll to the message.
244
- - `visible` (boolean): If `false`, the message is added to the history but not displayed. Defaults to `true`.
245
323
 
246
- ### `messageRemove(msgid)`
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
335
+ ```bash
336
+ git clone https://github.com/deftio/quikchat.git
337
+ cd quikchat
338
+ npm install
339
+ npm run dev
340
+ ```
247
341
 
248
- Removes a message from the chat by its ID.
342
+ **📋 [Contributing Guidelines](CONTRIBUTING.md)**
249
343
 
250
- ### `messageSetVisibility(msgid, isVisible)`
251
344
 
252
- Sets the visibility of a message that is already in the chat.
253
345
 
254
- - `msgid` (number): The ID of the message to modify.
255
- - `isVisible` (boolean): `true` to show the message, `false` to hide it.
346
+ ## 📄 License
256
347
 
257
- This is useful for hiding system prompts or for moderation.
348
+ QuikChat is licensed under the [BSD-2-Clause License](LICENSE.txt).
258
349
 
259
- ### `messageGetVisibility(msgid)`
260
350
 
261
- Checks if a message is currently visible.
262
351
 
263
- - `msgid` (number): The ID of the message to check.
264
- - Returns `true` if the message is visible, `false` otherwise.
352
+ ## 🔗 Links
265
353
 
266
- ### `messageRemoveLast()`
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)**
267
359
 
268
- Removes the most recently added message.